From 46ae6b49c171826547066f6ef4972008cd7abe54 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 8 Oct 2025 16:21:09 +0200 Subject: [PATCH] docs: move generated markdown into a package --- docs/nix/flake-module.nix | 72 +------------------ pkgs/docs-from-code/flake-module.nix | 71 ++++++++++++++++++ .../docs-from-code/generate}/__init__.py | 0 .../docs-from-code}/get-module-docs.nix | 0 pkgs/flake-module.nix | 1 + 5 files changed, 74 insertions(+), 70 deletions(-) create mode 100644 pkgs/docs-from-code/flake-module.nix rename {docs/nix/render_options => pkgs/docs-from-code/generate}/__init__.py (100%) rename {docs/nix => pkgs/docs-from-code}/get-module-docs.nix (100%) diff --git a/docs/nix/flake-module.nix b/docs/nix/flake-module.nix index 2543d19c3..3db6592b7 100644 --- a/docs/nix/flake-module.nix +++ b/docs/nix/flake-module.nix @@ -1,4 +1,4 @@ -{ inputs, self, ... }: +{ inputs, ... }: { perSystem = { @@ -7,74 +7,7 @@ pkgs, ... }: - let - # Simply evaluated options (JSON) - # { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; } - jsonDocs = pkgs.callPackage ./get-module-docs.nix { - inherit (self) clanModules; - clan-core = self; - inherit pkgs; - }; - - # clan service options - clanModulesViaService = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesViaService); - - # Simply evaluated options (JSON) - renderOptions = - pkgs.runCommand "render-options" - { - # TODO: ruff does not splice properly in nativeBuildInputs - depsBuildBuild = [ pkgs.ruff ]; - nativeBuildInputs = [ - pkgs.python3 - pkgs.mypy - self'.packages.clan-cli - ]; - } - '' - install -D -m755 ${./render_options}/__init__.py $out/bin/render-options - patchShebangs --build $out/bin/render-options - - ruff format --check --diff $out/bin/render-options - ruff check --line-length 88 $out/bin/render-options - mypy --strict $out/bin/render-options - ''; - - module-docs = - pkgs.runCommand "rendered" - { - buildInputs = [ - pkgs.python3 - self'.packages.clan-cli - ]; - } - '' - export CLAN_CORE_PATH=${ - inputs.nixpkgs.lib.fileset.toSource { - root = ../..; - fileset = ../../clanModules; - } - } - export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json - - # A file that contains the links to all clanModule docs - export CLAN_MODULES_VIA_SERVICE=${clanModulesViaService} - export CLAN_SERVICE_INTERFACE=${self'.legacyPackages.clan-service-module-interface}/share/doc/nixos/options.json - export CLAN_OPTIONS_PATH=${self'.legacyPackages.clan-options}/share/doc/nixos/options.json - - mkdir $out - - # The python script will place mkDocs files in the output directory - exec python3 ${renderOptions}/bin/render-options - ''; - in { - legacyPackages = { - inherit - jsonDocs - clanModulesViaService - ; - }; devShells.docs = self'.packages.docs.overrideAttrs (_old: { nativeBuildInputs = [ # Run: htmlproofer --disable-external @@ -96,12 +29,11 @@ option-search inventory-api-docs clan-lib-openapi + module-docs ; inherit (inputs) nixpkgs; - inherit module-docs; }; deploy-docs = pkgs.callPackage ./deploy-docs.nix { inherit (config.packages) docs; }; - inherit module-docs; }; checks.docs-integrity = pkgs.runCommand "docs-integrity" diff --git a/pkgs/docs-from-code/flake-module.nix b/pkgs/docs-from-code/flake-module.nix new file mode 100644 index 000000000..fd1dc1b4f --- /dev/null +++ b/pkgs/docs-from-code/flake-module.nix @@ -0,0 +1,71 @@ +{ self, inputs, ... }: +{ + perSystem = + { pkgs, self', ... }: + let + # Simply evaluated options (JSON) + # { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; } + jsonDocs = pkgs.callPackage ./get-module-docs.nix { + inherit (self) clanModules; + clan-core = self; + inherit pkgs; + }; + + # clan service options + clanModulesViaService = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesViaService); + + # Simply evaluated options (JSON) + renderOptions = + pkgs.runCommand "render-options" + { + # TODO: ruff does not splice properly in nativeBuildInputs + depsBuildBuild = [ pkgs.ruff ]; + nativeBuildInputs = [ + pkgs.python3 + pkgs.mypy + self'.packages.clan-cli + ]; + } + '' + install -D -m755 ${./generate}/__init__.py $out/bin/render-options + patchShebangs --build $out/bin/render-options + + ruff format --check --diff $out/bin/render-options + ruff check --line-length 88 $out/bin/render-options + mypy --strict $out/bin/render-options + ''; + + module-docs = + pkgs.runCommand "rendered" + { + buildInputs = [ + pkgs.python3 + self'.packages.clan-cli + ]; + } + '' + export CLAN_CORE_PATH=${ + inputs.nixpkgs.lib.fileset.toSource { + root = ../..; + fileset = ../../clanModules; + } + } + export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json + + # A file that contains the links to all clanModule docs + export CLAN_MODULES_VIA_SERVICE=${clanModulesViaService} + export CLAN_SERVICE_INTERFACE=${self'.legacyPackages.clan-service-module-interface}/share/doc/nixos/options.json + export CLAN_OPTIONS_PATH=${self'.legacyPackages.clan-options}/share/doc/nixos/options.json + + mkdir $out + + # The python script will place mkDocs files in the output directory + exec python3 ${renderOptions}/bin/render-options + ''; + in + { + packages = { + inherit module-docs; + }; + }; +} diff --git a/docs/nix/render_options/__init__.py b/pkgs/docs-from-code/generate/__init__.py similarity index 100% rename from docs/nix/render_options/__init__.py rename to pkgs/docs-from-code/generate/__init__.py diff --git a/docs/nix/get-module-docs.nix b/pkgs/docs-from-code/get-module-docs.nix similarity index 100% rename from docs/nix/get-module-docs.nix rename to pkgs/docs-from-code/get-module-docs.nix diff --git a/pkgs/flake-module.nix b/pkgs/flake-module.nix index bdf0911e9..75f4e6c81 100644 --- a/pkgs/flake-module.nix +++ b/pkgs/flake-module.nix @@ -9,6 +9,7 @@ ./icon-update/flake-module.nix ./installer/flake-module.nix ./option-search/flake-module.nix + ./docs-from-code/flake-module.nix ./testing/flake-module.nix ];