From 712ed3f738d69fec364a619785bc598f89bd28e3 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Mon, 24 Jun 2024 22:58:00 +0200 Subject: [PATCH] Docs: add inventory module docs --- clanModules/borgbackup-static/default.nix | 2 +- clanModules/borgbackup/README.md | 15 +------- clanModules/borgbackup/default.nix | 47 ++++++++++------------- docs/mkdocs.yml | 2 +- docs/nix/flake-module.nix | 2 + docs/nix/get-module-docs.nix | 7 +++- docs/nix/scripts/renderOptions.py | 47 +++++++++++++++++++++++ 7 files changed, 78 insertions(+), 44 deletions(-) diff --git a/clanModules/borgbackup-static/default.nix b/clanModules/borgbackup-static/default.nix index d65fdb5f..931ea15f 100644 --- a/clanModules/borgbackup-static/default.nix +++ b/clanModules/borgbackup-static/default.nix @@ -3,7 +3,7 @@ let clanDir = config.clan.core.clanDir; machineDir = clanDir + "/machines/"; in -lib.warn "This module is deprecated use the service via the service interface instead." { +lib.warn "This module is deprecated use the service via the inventory interface instead." { imports = [ ../borgbackup ]; options.clan.borgbackup-static = { diff --git a/clanModules/borgbackup/README.md b/clanModules/borgbackup/README.md index 13379d26..b639786d 100644 --- a/clanModules/borgbackup/README.md +++ b/clanModules/borgbackup/README.md @@ -1,15 +1,2 @@ Efficient, deduplicating backup program with optional compression and secure encryption. ---- - -## Roles - -- Client -- Server - -## Configuration - -Configure target machines where the backups should be sent to through `targets`. - -Configure machines that should be backed up either through `includeMachines` -which will exclusively add the included machines to be backed up, or through -`excludeMachines`, which will add every machine except the excluded machine to the backup. +--- \ No newline at end of file diff --git a/clanModules/borgbackup/default.nix b/clanModules/borgbackup/default.nix index f708fe2e..c5f61b3c 100644 --- a/clanModules/borgbackup/default.nix +++ b/clanModules/borgbackup/default.nix @@ -30,39 +30,37 @@ let # Each .nix file in the roles directory is a role # TODO: Helper function to set available roles within module meta. - # roles = lib.pipe ./roles [ - # (p: if builtins.pathExists p then p else throw "Role directory does not exist") - # builtins.readDir - # (lib.filterAttrs (_n: v: v == "regular")) - # lib.attrNames - # (map (fileName: lib.removeSuffix ".nix" fileName)) - # ]; + roles = + if builtins.pathExists ./roles then + lib.pipe ./roles [ + builtins.readDir + (lib.filterAttrs (_n: v: v == "regular")) + lib.attrNames + (map (fileName: lib.removeSuffix ".nix" fileName)) + ] + else + null; # TODO: make this an interface of every module # Maybe load from readme.md metaInfoOption = lib.mkOption { readOnly = true; default = { - description = "A category for the service. This is used to group services in the clan ui"; + description = "Borgbackup is a backup program. Optionally, it supports compression and authenticated encryption."; + availableRoles = roles; + category = "backup"; }; type = lib.types.submodule { options = { - description = lib.mkOption { + description = lib.mkOption { type = lib.types.str; }; + availableRoles = lib.mkOption { type = lib.types.nullOr (lib.types.listOf lib.types.str); }; + category = lib.mkOption { description = "A category for the service. This is used to group services in the clan ui"; - type = lib.types.str; + type = lib.types.enum [ + "backup" + "network" + ]; }; - # icon = lib.mkOption { - # description = "A category for the service. This is used to group services in the clan ui"; - # type = lib.types.str; - # }; - # screenshots = lib.mkOption { - # description = "A category for the service. This is used to group services in the clan ui"; - # type = lib.types.str; - # }; - # category = lib.mkOption { - # description = "A category for the service. This is used to group services in the clan ui"; - # type = lib.types.enum ["backup" "network"]; - # }; }; }; }; @@ -105,11 +103,6 @@ in }; imports = [ - { - config.clan.borgbackup.meta = { - description = "backup"; - }; - } (lib.mkRemovedOptionModule [ "clan" "borgbackup" diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index d43ee81b..daaf98e9 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -49,7 +49,7 @@ nav: - Mesh VPN: getting-started/mesh-vpn.md - Backup & Restore: getting-started/backups.md - Flake-parts: getting-started/flake-parts.md - - Modules: + - Reference: - Clan Modules: - reference/clanModules/borgbackup-static.md - reference/clanModules/borgbackup.md diff --git a/docs/nix/flake-module.nix b/docs/nix/flake-module.nix index b398db44..8370c0a2 100644 --- a/docs/nix/flake-module.nix +++ b/docs/nix/flake-module.nix @@ -19,6 +19,7 @@ clanModulesFileInfo = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModules); clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes); + clanModulesMeta = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesMeta); # Simply evaluated options (JSON) renderOptions = @@ -54,6 +55,7 @@ # A file that contains the links to all clanModule docs export CLAN_MODULES=${clanModulesFileInfo} export CLAN_MODULES_READMES=${clanModulesReadmes} + export CLAN_MODULES_META=${clanModulesMeta} mkdir $out diff --git a/docs/nix/get-module-docs.nix b/docs/nix/get-module-docs.nix index a05fe847..b1d2ed9d 100644 --- a/docs/nix/get-module-docs.nix +++ b/docs/nix/get-module-docs.nix @@ -43,11 +43,16 @@ let module_name: _module: self.lib.modules.getReadme module_name ) clanModules; + clanModulesMeta = builtins.mapAttrs ( + module_name: _module: + (self.lib.evalClanModules [ module_name ]).config.clan.${module_name}.meta or { } + ) clanModules; + # clanCore docs clanCoreDocs = (evalDocs (getOptions [ ]).clan.core).optionsJSON; in { - inherit clanModulesReadmes; + inherit clanModulesReadmes clanModulesMeta; clanCore = clanCoreDocs; clanModules = clanModulesDocs; } diff --git a/docs/nix/scripts/renderOptions.py b/docs/nix/scripts/renderOptions.py index 4480d410..096fbe32 100644 --- a/docs/nix/scripts/renderOptions.py +++ b/docs/nix/scripts/renderOptions.py @@ -32,6 +32,8 @@ from typing import Any CLAN_CORE = os.getenv("CLAN_CORE") CLAN_MODULES = os.environ.get("CLAN_MODULES") CLAN_MODULES_READMES = os.environ.get("CLAN_MODULES_READMES") +CLAN_MODULES_META = os.environ.get("CLAN_MODULES_META") + OUT = os.environ.get("out") @@ -198,6 +200,11 @@ def produce_clan_modules_docs() -> None: f"Environment variables are not set correctly: $CLAN_MODULES_READMES={CLAN_MODULES_READMES}" ) + if not CLAN_MODULES_META: + raise ValueError( + f"Environment variables are not set correctly: $CLAN_MODULES_META={CLAN_MODULES_META}" + ) + if not OUT: raise ValueError(f"Environment variables are not set correctly: $out={OUT}") @@ -207,6 +214,42 @@ def produce_clan_modules_docs() -> None: with open(CLAN_MODULES_READMES) as readme: readme_map: dict[str, str] = json.load(readme) + with open(CLAN_MODULES_META) as f: + meta_map: dict[str, Any] = json.load(f) + print(meta_map) + + def render_meta(meta: dict[str, Any], module_name: str) -> str: + roles = meta.get("availableRoles", None) + + if roles: + roles_list = "\n".join([f" - `{r}`" for r in roles]) + return f""" +???+ tip "Inventory (WIP)" + + Predefined roles: + +{roles_list} + + Usage: + + ```{{.nix hl_lines="4"}} + buildClan {{ + inventory.services = {{ + {module_name}.instance_1 = {{ + roles.{roles[0]}.machines = [ "sara_machine" ]; + # ... + }}; + }}; + }} + ``` + +""" + return """ +???+ example "Inventory (WIP)" + This module does not support the inventory yet. + + """ + # {'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: @@ -217,6 +260,10 @@ def produce_clan_modules_docs() -> None: if readme_map.get(module_name, None): output += f"{readme_map[module_name]}\n" + # Add meta information: + # - Inventory implementation status + output += render_meta(meta_map.get(module_name, {}), module_name) + output += module_usage(module_name) output += options_head if len(options.items()) else ""