From 87559613ed7b03622fd8723bb96b04a1ac75e10d Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 17 Apr 2024 12:52:04 +0200 Subject: [PATCH] docs: add clan modules readme support --- clanModules/flake-module.nix | 2 +- clanModules/root-password/README.md | 13 +++++++++ .../default.nix} | 0 docs/nix/flake-module.nix | 7 ++++- docs/nix/get-module-docs.nix | 19 +++++++++++++ docs/nix/scripts/renderOptions.py | 28 +++++++++++++------ 6 files changed, 58 insertions(+), 11 deletions(-) create mode 100644 clanModules/root-password/README.md rename clanModules/{root-password.nix => root-password/default.nix} (100%) diff --git a/clanModules/flake-module.nix b/clanModules/flake-module.nix index b58022430..de70b0c8e 100644 --- a/clanModules/flake-module.nix +++ b/clanModules/flake-module.nix @@ -18,7 +18,7 @@ sshd = ./sshd.nix; sunshine = ./sunshine.nix; syncthing = ./syncthing.nix; - root-password = ./root-password.nix; + root-password = ./root-password; thelounge = ./thelounge.nix; vm-user = ./vm-user.nix; waypipe = ./waypipe.nix; diff --git a/clanModules/root-password/README.md b/clanModules/root-password/README.md new file mode 100644 index 000000000..fd940a7d4 --- /dev/null +++ b/clanModules/root-password/README.md @@ -0,0 +1,13 @@ +## Usage + +!!! tip "This module sets the password for the root user (automatically)." + +After the system was installed/deployed the following command can be used to display the root-password: + +```bash +clan secrets get {machine_name}-password +``` + +--- + +See also: [Facts / Secrets](../../getting-started/secrets.md) diff --git a/clanModules/root-password.nix b/clanModules/root-password/default.nix similarity index 100% rename from clanModules/root-password.nix rename to clanModules/root-password/default.nix diff --git a/docs/nix/flake-module.nix b/docs/nix/flake-module.nix index 67a8b5051..a0560e4fc 100644 --- a/docs/nix/flake-module.nix +++ b/docs/nix/flake-module.nix @@ -12,12 +12,13 @@ # { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; } jsonDocs = import ./get-module-docs.nix { inherit (inputs) nixpkgs; - inherit pkgs; + inherit pkgs self; inherit (self.nixosModules) clanCore; inherit (self) clanModules; }; clanModulesFileInfo = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModules); + clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes); # Simply evaluated options (JSON) renderOptions = @@ -43,6 +44,7 @@ export CLAN_CORE=${jsonDocs.clanCore}/share/doc/nixos/options.json # A file that contains the links to all clanModule docs export CLAN_MODULES=${clanModulesFileInfo} + export CLAN_MODULES_READMES=${clanModulesReadmes} mkdir $out @@ -63,5 +65,8 @@ deploy-docs = pkgs.callPackage ./deploy-docs.nix { inherit (config.packages) docs; }; inherit module-docs; }; + legacyPackages = { + foo = jsonDocs; + }; }; } diff --git a/docs/nix/get-module-docs.nix b/docs/nix/get-module-docs.nix index 1bb9d3337..05e027668 100644 --- a/docs/nix/get-module-docs.nix +++ b/docs/nix/get-module-docs.nix @@ -3,6 +3,7 @@ pkgs, clanCore, clanModules, + self, }: let allNixosModules = (import "${nixpkgs}/nixos/modules/module-list.nix") ++ [ @@ -36,10 +37,28 @@ let name: module: (evalDocs ((getOptions [ module ]).clan.${name} or { })).optionsJSON ) clanModules; + clanModulesReadmes = builtins.mapAttrs ( + module_name: _module: + let + readme = "${self}/clanModules/${module_name}/README.md"; + readmeContents = + if + builtins.trace "Trying to get Module README.md for ${module_name} from ${readme}" + # TODO: Edge cases + (builtins.pathExists readme) + then + (builtins.readFile readme) + else + null; + in + readmeContents + ) clanModules; + # clanCore docs clanCoreDocs = (evalDocs (getOptions [ ]).clanCore).optionsJSON; in { + inherit clanModulesReadmes; clanCore = clanCoreDocs; clanModules = clanModulesDocs; } diff --git a/docs/nix/scripts/renderOptions.py b/docs/nix/scripts/renderOptions.py index 080f4efbb..a679936a2 100644 --- a/docs/nix/scripts/renderOptions.py +++ b/docs/nix/scripts/renderOptions.py @@ -31,6 +31,8 @@ from typing import Any # Get environment variables CLAN_CORE = os.getenv("CLAN_CORE") CLAN_MODULES = os.environ.get("CLAN_MODULES") +CLAN_MODULES_READMES = os.environ.get("CLAN_MODULES_READMES") + OUT = os.environ.get("out") @@ -74,9 +76,9 @@ def render_option(name: str, option: dict[str, Any]) -> str: if example: res += f""" -??? example +???+ example - ```nix + ```nix {example} ``` """ @@ -121,9 +123,7 @@ def produce_clan_core_docs() -> None: raise ValueError(f"Environment variables are not set correctly: $out={OUT}") # A mapping of output file to content - core_outputs: dict[str, str] = { - "clan-core/index.md": "", - } + core_outputs: dict[str, str] = {} with open(CLAN_CORE) as f: options: dict[str, dict[str, Any]] = json.load(f) module_name = "clan-core" @@ -133,10 +133,10 @@ def produce_clan_core_docs() -> None: # Create seperate files for nested options if len(option_name.split(".")) <= 2: # i.e. clan-core.clanDir - output = module_header(module_name) + output = core_outputs.get(outfile, module_header(module_name)) output += render_option(option_name, info) - core_outputs[outfile] += output - + # Update the content + core_outputs[outfile] = output else: # Clan sub-options [_, sub] = option_name.split(".")[0:2] @@ -147,7 +147,6 @@ def produce_clan_core_docs() -> None: # Update the content core_outputs[outfile] = output - print(core_outputs) for outfile, output in core_outputs.items(): (Path(OUT) / outfile).parent.mkdir(parents=True, exist_ok=True) with open(Path(OUT) / outfile, "w") as of: @@ -159,6 +158,10 @@ def produce_clan_modules_docs() -> None: raise ValueError( f"Environment variables are not set correctly: $CLAN_MODULES={CLAN_MODULES}" ) + if not CLAN_MODULES_READMES: + raise ValueError( + f"Environment variables are not set correctly: $CLAN_MODULES_READMES={CLAN_MODULES_READMES}" + ) if not OUT: raise ValueError(f"Environment variables are not set correctly: $out={OUT}") @@ -166,12 +169,19 @@ def produce_clan_modules_docs() -> None: with open(CLAN_MODULES) as f: links: dict[str, str] = json.load(f) + with open(CLAN_MODULES_READMES) as readme: + readme_map: dict[str, str] = json.load(readme) + # {'borgbackup': '/nix/store/hi17dwgy7963ddd4ijh81fv0c9sbh8sw-options.json', ... } for module_name, options_file in links.items(): with open(Path(options_file) / "share/doc/nixos/options.json") as f: options: dict[str, dict[str, Any]] = json.load(f) print(f"Rendering options for {module_name}...") output = module_header(module_name) + + if readme_map.get(module_name, None): + output += f"{readme_map[module_name]}\n" + for option_name, info in options.items(): output += render_option(option_name, info)