Skip to content

Commit

Permalink
Generate a basic reference documentation site
Browse files Browse the repository at this point in the history
  • Loading branch information
barrucadu committed Oct 15, 2023
1 parent bc517fb commit 37b5aa0
Show file tree
Hide file tree
Showing 7 changed files with 127 additions and 10 deletions.
6 changes: 6 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,9 @@ jobs:
nix run .#fmt
nix run .#lint
git diff --exit-code
- name: Check mdbook-admonish changes are not committed
run: |
if grep -q "do not edit: managed by \`mdbook-admonish install\`" docs/book.toml; then
echo "remove generated mdbook-admonish lines from docs/books.toml" >&2
exit 1
fi
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/_site
7 changes: 7 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
book

# generated by the build script
src/README.md
src/modules.md
src/options.md
mdbook-admonish.css
17 changes: 17 additions & 0 deletions docs/book.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[book]
title = "nixfiles"
authors = ["Michael Walker (barrucadu)"]
description = "My NixOS configuration and assorted other crap, powered by flakes."
language = "en"
multilingual = false

[build]
create-missing = false

[output.html]
git-repository-url = "https://github.com/barrucadu/nixfiles"
cname = "nixfiles.docs.barrucadu.co.uk"

[preprocessor.admonish]
on_failure = "bail"
command = "mdbook-admonish"
8 changes: 8 additions & 0 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Summary

- [README](./README.md)

# Reference

- [Modules](./modules.md)
- [Options](./options.md)
16 changes: 6 additions & 10 deletions flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@
${pkgs.lib.fileContents ./scripts/secrets.sh}
'';

option-docs =
documentation =
let
eval = pkgs.lib.evalModules {
modules = [
Expand All @@ -115,15 +115,11 @@
warningsAreErrors = false;
};
in
mkApp "options-json" ''
case "$1" in
"json")
cat ${optionsDoc.optionsJSON}/share/doc/nixos/options.json
;;
*)
cat ${optionsDoc.optionsCommonMark}
;;
esac
mkApp "documentation" ''
PATH=${with pkgs; lib.makeBinPath [ coreutils mdbook mdbook-admonish python3 ]}
export NIXOS_OPTIONS_JSON="${optionsDoc.optionsJSON}/share/doc/nixos/options.json"
${pkgs.lib.fileContents ./scripts/documentation.sh}
'';
};
};
Expand Down
82 changes: 82 additions & 0 deletions scripts/documentation.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
set -e

pushd docs
mdbook-admonish install
popd

cp README.markdown docs/src/README.md

python3 - <<'EOF' > docs/src/modules.md
import json
import os
print("# Modules")
print("")
with open(os.getenv("NIXOS_OPTIONS_JSON"), "r") as f:
options = json.load(f)
modules = {}
for key, defn in options.items():
module_name = defn["declarations"][0].split("/shared/")[1].replace("/options.nix", "")
if module_name == "options.nix":
# this is the top-level `shared` file
module_name = ""
modules.setdefault(module_name, []).append(key)
for module in sorted(modules.keys()):
module_name = "&lt;shared&gt;" if module == "" else module
source_file = f"shared/{module}/default.nix".replace("//", "/")
print(f"## {module_name}")
print(f"\n**Description:**")
has_doc = False
with open(source_file, "r") as f:
for line in f:
if line.startswith("# "):
has_doc = True
print(line[2:].strip())
else:
break
if not has_doc:
print("This module has no description.")
print("\n**Options:**\n")
for option in modules[module]:
anchor = "".join(c for c in option if c.isalpha() or c == "-")
print(f"- [`{option}`](./options.md#{anchor})")
print(f"\n**Declared in:** [{source_file}](https://github.com/barrucadu/nixfiles/blob/master/{source_file})")
print("")
EOF

python3 - <<'EOF' > docs/src/options.md
import json
import os
print("# Options")
print("")
with open(os.getenv("NIXOS_OPTIONS_JSON"), "r") as f:
options = json.load(f)
for option in sorted(options.keys()):
defn = options[option]
option_name = option.replace("*", "\\*").replace("<", "&lt;").replace(">", "&gt;")
source_file = "shared/" + defn["declarations"][0].split("/shared/")[1]
print(f"## {option_name}")
print(f"\n**Description:** {defn['description']}")
print(f"\n**Type:** `{defn['type']}`")
if "default" in defn:
print(f"\n**Default:** `{defn['default']['text']}`")
print(f"\n**Declared in:** [{source_file}](https://github.com/barrucadu/nixfiles/blob/master/{source_file})")
print("")
EOF

mdbook build docs
mv docs/book _site

chmod -c -R +rX _site | while read -r line; do
echo "::warning title=Invalid file permissions automatically fixed::$line"
done

0 comments on commit 37b5aa0

Please sign in to comment.