fujin/nixarr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improved documentation generation, no more hacky sed/awk!

Browse Source
This commit is contained in:
rasmus-kirk
2024-02-28 12:16:25 +01:00
parent c5397fb4df
commit 906a8c3a50
9 changed files with 181 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pandoc/anchor-links.lua → docs/pandoc/lua/anchor-links.lua
View File
docs/pandoc/lua/code-default-to-nix.lua
+9
View File
@@ -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
+8
View File
@@ -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
+31
View File
@@ -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
+17
View File
@@ -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
+47
View File
@@ -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
+47
View File
@@ -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
+11 -31
View File
@@ -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 \
nixarr/openssh/default.nix
+11 -7
View File
@@ -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!
'';
};