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