Improved documentation generation, no more hacky sed/awk!

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

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

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

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

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

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

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
+      cat ${optionsDocNixos.optionsCommonMark} > "$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
 
       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
+        "$tmpdir"/nixos.md
-
-      tail -n +2 README.md > "$tmpdir/index.md"
 
       pandoc \
         --standalone \

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!
     '';
   };