forked from clan/clan-core
Docs: add inventory module docs
This commit is contained in:
parent
e6c78054c4
commit
712ed3f738
@ -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 = {
|
||||
|
@ -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.
|
||||
|
@ -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"
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
||||
|
@ -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;
|
||||
}
|
||||
|
@ -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 ""
|
||||
|
Loading…
Reference in New Issue
Block a user