From 6c097699f4bb477b383a826efcc68c8be1f253ca Mon Sep 17 00:00:00 2001 From: lassulus Date: Sun, 16 Nov 2025 01:14:49 +0700 Subject: [PATCH 1/3] WIP: add docs output this will add some documentation to the generated modules when done, currently this has a few flaws Things TOOD: - generate documentation for internal module - filter out the baseModule options - remove the stuff about nixos internals Maybe a better approach would be a pure approach where ge generate the strings directly, instead of relying on nixosOptionsDoc, which requires pkgs. --- lib/default.nix | 3 ++- lib/modules/doc.nix | 53 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 lib/modules/doc.nix diff --git a/lib/default.nix b/lib/default.nix index 52ecc71..2a80dbf 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -218,7 +218,7 @@ let inherit modules class specialArgs; }; - modules = lib.genAttrs [ "package" "wrapper" "meta" ] (name: import ./modules/${name}.nix); + modules = lib.genAttrs [ "doc" "package" "wrapper" "meta" ] (name: import ./modules/${name}.nix); /** Create a wrapper configuration using the NixOS module system. @@ -332,6 +332,7 @@ let }; } ) + modules.doc modules.wrapper modules.meta wrapperModule diff --git a/lib/modules/doc.nix b/lib/modules/doc.nix new file mode 100644 index 0000000..696f947 --- /dev/null +++ b/lib/modules/doc.nix @@ -0,0 +1,53 @@ +{ + options, + config, + lib, + wlib, + ... +}: +let + internalOptions = lib.flatten ( + builtins.attrValues ( + builtins.mapAttrs ( + _: mod: + builtins.attrNames + (mod { + lib = null; + wlib = null; + config = null; + options = null; + }).options + ) wlib.modules + ) + ); + optionsToRender = builtins.removeAttrs options config.docs.ignoreOptions; + nixosOptionsDoc = config.pkgs.nixosOptionsDoc { + options = optionsToRender; + warningsAreErrors = config.docs.warningsAreErrors; + }; +in +{ + options.docs = { + ignoreOptions = lib.mkOption { + type = lib.types.listOf lib.types.str; + default = internalOptions; + }; + warningsAreErrors = lib.mkOption { + type = lib.types.bool; + default = false; # TODO make this true + description = "Whether warnings during documentation generation should be treated as errors."; + }; + asciiDoc = lib.mkOption { + type = lib.types.package; + default = nixosOptionsDoc.optionsAsciiDoc; + }; + commonMark = lib.mkOption { + type = lib.types.package; + default = nixosOptionsDoc.optionsCommonMark; + }; + json = lib.mkOption { + type = lib.types.package; + default = nixosOptionsDoc.optionsJSON; + }; + }; +} From 65c3f102376f6a53dd1a05ea9abe20a8d8384f19 Mon Sep 17 00:00:00 2001 From: zimward Date: Tue, 13 Jan 2026 19:42:38 +0100 Subject: [PATCH 2/3] WIP: add HTML docs --- lib/modules/doc.nix | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/lib/modules/doc.nix b/lib/modules/doc.nix index 696f947..7e6442d 100644 --- a/lib/modules/doc.nix +++ b/lib/modules/doc.nix @@ -20,7 +20,7 @@ let ) wlib.modules ) ); - optionsToRender = builtins.removeAttrs options config.docs.ignoreOptions; + optionsToRender = removeAttrs options config.docs.ignoreOptions; nixosOptionsDoc = config.pkgs.nixosOptionsDoc { options = optionsToRender; warningsAreErrors = config.docs.warningsAreErrors; @@ -49,5 +49,17 @@ in type = lib.types.package; default = nixosOptionsDoc.optionsJSON; }; + html = lib.mkOption { + type = lib.types.package; + default = config.pkgs.stdenvNoCC.mkDerivation { + name = "docs-${config.package.name}.html"; + src = config.docs.commonMark; + dontUnpack = true; + nativeBuildInputs = [ config.pkgs.pandoc ]; + buildPhase = '' + pandoc -f markdown -t html $src > $out + ''; + }; + }; }; } From 38d772292d0db9bda1797c438b28883a5296e257 Mon Sep 17 00:00:00 2001 From: zimward Date: Fri, 20 Mar 2026 22:54:54 +0100 Subject: [PATCH 3/3] doc: add mdbook package flake output --- flake.nix | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/flake.nix b/flake.nix index 187086e..e95449b 100644 --- a/flake.nix +++ b/flake.nix @@ -5,6 +5,8 @@ { self, nixpkgs }: let forAllSystems = f: nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all (system: f system); + # non-exhaustive list of systems nixpkgs has support for + defaultSystems = f: nixpkgs.lib.genAttrs [ "x86_64-linux" "aarch64-linux" ] (system: f system); in { lib = import ./lib { lib = nixpkgs.lib; }; @@ -58,5 +60,45 @@ in checksFromDir // checksFromModules ); + # mdbook documentation for all modules + packages = defaultSystems ( + system: + let + pkgs = nixpkgs.legacyPackages.${system}; + lib = nixpkgs.lib; + in + { + mdbook = ( + pkgs.stdenvNoCC.mkDerivation { + name = "wrappers-mdbook"; + nativeBuildInputs = with pkgs; [ + mdbook + ]; + srcs = lib.mapAttrsToList (_: v: ((v.apply { inherit pkgs; }).docs.commonMark)) self.wrapperModules; + names = lib.mapAttrsToList (name: _: name) self.wrapperModules; + dontUnpack = true; + dontPatch = true; + buildPhase = '' + # echo "[book]" >> book.toml + # echo "title = \"wrappers\"" >> book.toml + mdbook init wrappers + cd wrappers/src + echo "# Summary" > SUMMARY.md + names=($names) + srcs=($srcs) + for i in "''${!names[@]}"; do + cp ''${srcs[$i]} ''${names[$i]}.md + + echo "- ["''${names[$i]}"](''${names[$i]}.md)" >> SUMMARY.md + done + cat SUMMARY.md + mkdir -p $out + cd .. + mdbook build --dest-dir $out + ''; + } + ); + } + ); }; }