From 906a8c3a509beb10ec2f0ab45ac77bb1a3a13df3 Mon Sep 17 00:00:00 2001 From: rasmus-kirk Date: Wed, 28 Feb 2024 12:16:25 +0100 Subject: [PATCH] Improved documentation generation, no more hacky sed/awk! --- docs/pandoc/{ => lua}/anchor-links.lua | 0 docs/pandoc/lua/code-default-to-nix.lua | 9 +++++ docs/pandoc/lua/headers-lvl2-to-lvl3.lua | 8 ++++ docs/pandoc/lua/inline-to-fenced-nix.lua | 31 ++++++++++++++++ docs/pandoc/lua/remove-declared-by.lua | 17 +++++++++ docs/pandoc/lua/remove-module-args.lua | 47 ++++++++++++++++++++++++ docs/pandoc/lua/remove-utils.lua | 47 ++++++++++++++++++++++++ mkDocs.nix | 42 ++++++--------------- nixarr/openssh/default.nix | 18 +++++---- 9 files changed, 181 insertions(+), 38 deletions(-) rename docs/pandoc/{ => lua}/anchor-links.lua (100%) create mode 100644 docs/pandoc/lua/code-default-to-nix.lua create mode 100644 docs/pandoc/lua/headers-lvl2-to-lvl3.lua create mode 100644 docs/pandoc/lua/inline-to-fenced-nix.lua create mode 100644 docs/pandoc/lua/remove-declared-by.lua create mode 100644 docs/pandoc/lua/remove-module-args.lua create mode 100644 docs/pandoc/lua/remove-utils.lua diff --git a/docs/pandoc/anchor-links.lua b/docs/pandoc/lua/anchor-links.lua similarity index 100% rename from docs/pandoc/anchor-links.lua rename to docs/pandoc/lua/anchor-links.lua diff --git a/docs/pandoc/lua/code-default-to-nix.lua b/docs/pandoc/lua/code-default-to-nix.lua new file mode 100644 index 0000000..2996610 --- /dev/null +++ b/docs/pandoc/lua/code-default-to-nix.lua @@ -0,0 +1,9 @@ +-- This function is called for each CodeBlock element in the document. +function CodeBlock(block) + -- Check if the code block does not have a language specified. + if block.classes[1] == nil then + -- Set the language of the code block to "nix". + block.classes[1] = "nix" + end + return block +end diff --git a/docs/pandoc/lua/headers-lvl2-to-lvl3.lua b/docs/pandoc/lua/headers-lvl2-to-lvl3.lua new file mode 100644 index 0000000..5d03bf6 --- /dev/null +++ b/docs/pandoc/lua/headers-lvl2-to-lvl3.lua @@ -0,0 +1,8 @@ +function Header(elem) + -- Check if the header is of level 2 + if elem.level == 2 then + -- Change the header level to 3 + elem.level = 3 + end + return elem +end diff --git a/docs/pandoc/lua/inline-to-fenced-nix.lua b/docs/pandoc/lua/inline-to-fenced-nix.lua new file mode 100644 index 0000000..f4acf48 --- /dev/null +++ b/docs/pandoc/lua/inline-to-fenced-nix.lua @@ -0,0 +1,31 @@ +-- file: remove-declared-by.lua + +function Para(elem) + -- Check if the first element of the paragraph is Emph (italic) + if #elem.content >= 1 and elem.content[1].t == "Emph" then + -- Convert the first element to plain text to check its content + local firstText = pandoc.utils.stringify(elem.content[1]) + local isExample = firstText:find("^Example:") + local isDefault = firstText:find("^Default:") + + -- Check if the text starts with "Declared by:" + if isExample or isDefault then + local newElems = {} + for i, el in ipairs(elem.content) do + if el.t == "Code" then + -- Convert inline code to fenced code block and add it to new elements + -- Note: This will be outside the paragraph due to block-level constraint + local addedSpaces = string.gsub(el.text, "^", " "); + table.insert(newElems, pandoc.CodeBlock(addedSpaces, pandoc.Attr("", {"nix"}))) + else + -- Keep other elements as inline, to be added to a new paragraph + table.insert(newElems, el) + end + end + -- Replace paragraph with new elements (mixing inline and block-level elements isn't directly possible, so this part needs rethinking) + return newElems + end + end + -- Otherwise, return the paragraph unmodified + return elem +end diff --git a/docs/pandoc/lua/remove-declared-by.lua b/docs/pandoc/lua/remove-declared-by.lua new file mode 100644 index 0000000..6474d3b --- /dev/null +++ b/docs/pandoc/lua/remove-declared-by.lua @@ -0,0 +1,17 @@ +-- file: remove-declared-by.lua + +function Para(elem) + -- Check if the first element of the paragraph is Emph (italic) + if #elem.content >= 1 and elem.content[1].t == "Emph" then + -- Convert the first element to plain text to check its content + local firstText = pandoc.utils.stringify(elem.content[1]) + + -- Check if the text starts with "Declared by:" + if firstText:find("^Declared by:") then + -- Return an empty block to remove this paragraph + return {} + end + end + -- Otherwise, return the paragraph unmodified + return elem +end diff --git a/docs/pandoc/lua/remove-module-args.lua b/docs/pandoc/lua/remove-module-args.lua new file mode 100644 index 0000000..ded832a --- /dev/null +++ b/docs/pandoc/lua/remove-module-args.lua @@ -0,0 +1,47 @@ +-- file: remove-util-nixarr.lua + +-- This function checks if a string starts with a given start string +function starts_with(str, start) + return str:sub(1, #start) == start +end + +-- This recursive function traverses the AST and removes sections based on the header condition +function remove_sections(elements, condition) + local result = {} + local skip_level = nil -- Define skip_level outside the loop, initialized to nil + + for _, el in ipairs(elements) do + if el.t == "Header" then + -- Check if we are currently skipping sections and this header is of equal or higher level + if skip_level and el.level <= skip_level then + skip_level = nil -- Stop skipping sections + end + + -- If skip_level is nil, check if this header starts a new section to skip + if not skip_level and condition(el) then + skip_level = el.level -- Start skipping sections + else + table.insert(result, el) -- Add the header to results if not skipping + end + elseif not skip_level then + table.insert(result, el) -- Add non-header elements if not skipping + end + end + + return result +end + +-- The Pandoc filter function to apply our custom logic +function Pandoc(doc) + -- Define the condition function to be used for identifying sections to remove + local condition = function(header) + -- Assuming the header's actual text is in the 'content' array and in the first element + local header_text = pandoc.utils.stringify(header.content) + return starts_with(header_text, "_module.args") + end + + -- Apply the removal function to the document blocks + doc.blocks = remove_sections(doc.blocks, condition) + + return doc +end diff --git a/docs/pandoc/lua/remove-utils.lua b/docs/pandoc/lua/remove-utils.lua new file mode 100644 index 0000000..4197a6a --- /dev/null +++ b/docs/pandoc/lua/remove-utils.lua @@ -0,0 +1,47 @@ +-- file: remove-util-nixarr.lua + +-- This function checks if a string starts with a given start string +function starts_with(str, start) + return str:sub(1, #start) == start +end + +-- This recursive function traverses the AST and removes sections based on the header condition +function remove_sections(elements, condition) + local result = {} + local skip_level = nil -- Define skip_level outside the loop, initialized to nil + + for _, el in ipairs(elements) do + if el.t == "Header" then + -- Check if we are currently skipping sections and this header is of equal or higher level + if skip_level and el.level <= skip_level then + skip_level = nil -- Stop skipping sections + end + + -- If skip_level is nil, check if this header starts a new section to skip + if not skip_level and condition(el) then + skip_level = el.level -- Start skipping sections + else + table.insert(result, el) -- Add the header to results if not skipping + end + elseif not skip_level then + table.insert(result, el) -- Add non-header elements if not skipping + end + end + + return result +end + +-- The Pandoc filter function to apply our custom logic +function Pandoc(doc) + -- Define the condition function to be used for identifying sections to remove + local condition = function(header) + -- Assuming the header's actual text is in the 'content' array and in the first element + local header_text = pandoc.utils.stringify(header.content) + return starts_with(header_text, "util-nixarr") + end + + -- Apply the removal function to the document blocks + doc.blocks = remove_sections(doc.blocks, condition) + + return doc +end diff --git a/mkDocs.nix b/mkDocs.nix index 718dc69..69c42a0 100644 --- a/mkDocs.nix +++ b/mkDocs.nix @@ -29,35 +29,11 @@ in mkdir -p $out mkdir -p $tmpdir cp -r docs $out + tail -n +2 README.md > "$tmpdir/index.md" + cd $out # Generate md docs - cat ${optionsDocNixos.optionsCommonMark} | tail -n +58 >> "$tmpdir"/nixos.md - - # Remove "Declared by" lines - sed -i '/\*Declared by:\*/{N;d;}' "$tmpdir"/nixos.md - - # Code blocks to nix code blocks - # shellcheck disable=SC2016 - awk ' - /^```$/ { - if (!block) { - print "```nix"; # Start of a code block - block = 1; - } else { - print "```"; # End of a code block - block = 0; - } - next; - } - { print } # Print all lines, including those inside code blocks - ' block=0 "$tmpdir"/nixos.md > "$tmpdir"/1.md - # inline code "blocks" to nix code blocks - # shellcheck disable=SC2016 - sed '/^`[^`]*`$/s/`\(.*\)`/```nix\n\1\n```/g' "$tmpdir"/1.md > "$tmpdir"/2.md - # Remove bottom util-nixarr options - sed '/util-nixarr/,$d' "$tmpdir"/2.md > "$tmpdir"/3.md - # Make h2 header to h3 - sed 's/^##/###/g' "$tmpdir"/3.md > "$tmpdir"/done.md + cat ${optionsDocNixos.optionsCommonMark} > "$tmpdir"/nixos.md pandoc \ --standalone \ @@ -66,14 +42,18 @@ in --template docs/pandoc/template.html \ --metadata date="$(date -u '+%Y-%m-%d - %H:%M:%S %Z')" \ --css docs/pandoc/style.css \ - --lua-filter docs/pandoc/anchor-links.lua \ + --lua-filter docs/pandoc/lua/anchor-links.lua \ + --lua-filter docs/pandoc/lua/code-default-to-nix.lua \ + --lua-filter docs/pandoc/lua/remove-utils.lua \ + --lua-filter docs/pandoc/lua/headers-lvl2-to-lvl3.lua \ + --lua-filter docs/pandoc/lua/remove-declared-by.lua \ + --lua-filter docs/pandoc/lua/inline-to-fenced-nix.lua \ + --lua-filter docs/pandoc/lua/remove-module-args.lua \ -V lang=en \ -V --mathjax \ -f markdown+smart \ -o $out/options.html \ - "$tmpdir"/done.md - - tail -n +2 README.md > "$tmpdir/index.md" + "$tmpdir"/nixos.md pandoc \ --standalone \ diff --git a/nixarr/openssh/default.nix b/nixarr/openssh/default.nix index 34cb8e7..ccca227 100644 --- a/nixarr/openssh/default.nix +++ b/nixarr/openssh/default.nix @@ -7,15 +7,19 @@ with lib; let cfg = config.nixarr.openssh; nixarr = config.nixarr; in { - options.nixarr.openssh.vpn.enable = mkOption { + options.nixarr.openssh.expose.vpn.enable = mkOption { type = types.bool; default = false; description = '' **Required options:** [`nixarr.vpn.enable`](#nixarr.vpn.enable) - Run the openssh service through a vpn. + Run the openssh service through a vpn, exposing it to the internet. - **Note:** This option does _not_ enable the sshd service you still + **Important:** This lets anyone on the internet connect through SSH, + make sure the SSH configuration is secure! Disallowing password + authentication and only allowing SSH-keys is considered secure. + + **Note:** This option does _not_ enable the SSHD service you still need to setup sshd in your nixos configuration, fx: ```nix @@ -29,11 +33,11 @@ in { users.extraUsers.username.openssh.authorizedKeys.keyFiles = [ ./path/to/public/key/machine.pub ]; - - Then replace username with your username and the keyFiles path - to a ssh public key file from the machine that you want to have - access. Don't use password authentication as it is insecure! ``` + + Then replace `username` with your username and the `keyFiles` path to a + ssh public key file from the machine that you want to have access. Don't + use password authentication as it is insecure! ''; };