Merge pull request 'docs: add clan modules readme support' (#1237) from hsjobeki-main into main

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;

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)

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;
+      };
     };
 }

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;
 }

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)