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;
|
clanDir = config.clan.core.clanDir;
|
||||||
machineDir = clanDir + "/machines/";
|
machineDir = clanDir + "/machines/";
|
||||||
in
|
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 ];
|
imports = [ ../borgbackup ];
|
||||||
|
|
||||||
options.clan.borgbackup-static = {
|
options.clan.borgbackup-static = {
|
||||||
|
@ -1,15 +1,2 @@
|
|||||||
Efficient, deduplicating backup program with optional compression and secure encryption.
|
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
|
# Each .nix file in the roles directory is a role
|
||||||
# TODO: Helper function to set available roles within module meta.
|
# TODO: Helper function to set available roles within module meta.
|
||||||
# roles = lib.pipe ./roles [
|
roles =
|
||||||
# (p: if builtins.pathExists p then p else throw "Role directory does not exist")
|
if builtins.pathExists ./roles then
|
||||||
# builtins.readDir
|
lib.pipe ./roles [
|
||||||
# (lib.filterAttrs (_n: v: v == "regular"))
|
builtins.readDir
|
||||||
# lib.attrNames
|
(lib.filterAttrs (_n: v: v == "regular"))
|
||||||
# (map (fileName: lib.removeSuffix ".nix" fileName))
|
lib.attrNames
|
||||||
# ];
|
(map (fileName: lib.removeSuffix ".nix" fileName))
|
||||||
|
]
|
||||||
|
else
|
||||||
|
null;
|
||||||
|
|
||||||
# TODO: make this an interface of every module
|
# TODO: make this an interface of every module
|
||||||
# Maybe load from readme.md
|
# Maybe load from readme.md
|
||||||
metaInfoOption = lib.mkOption {
|
metaInfoOption = lib.mkOption {
|
||||||
readOnly = true;
|
readOnly = true;
|
||||||
default = {
|
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 {
|
type = lib.types.submodule {
|
||||||
options = {
|
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";
|
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 = [
|
imports = [
|
||||||
{
|
|
||||||
config.clan.borgbackup.meta = {
|
|
||||||
description = "backup";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
(lib.mkRemovedOptionModule [
|
(lib.mkRemovedOptionModule [
|
||||||
"clan"
|
"clan"
|
||||||
"borgbackup"
|
"borgbackup"
|
||||||
|
@ -49,7 +49,7 @@ nav:
|
|||||||
- Mesh VPN: getting-started/mesh-vpn.md
|
- Mesh VPN: getting-started/mesh-vpn.md
|
||||||
- Backup & Restore: getting-started/backups.md
|
- Backup & Restore: getting-started/backups.md
|
||||||
- Flake-parts: getting-started/flake-parts.md
|
- Flake-parts: getting-started/flake-parts.md
|
||||||
- Modules:
|
- Reference:
|
||||||
- Clan Modules:
|
- Clan Modules:
|
||||||
- reference/clanModules/borgbackup-static.md
|
- reference/clanModules/borgbackup-static.md
|
||||||
- reference/clanModules/borgbackup.md
|
- reference/clanModules/borgbackup.md
|
||||||
|
@ -19,6 +19,7 @@
|
|||||||
|
|
||||||
clanModulesFileInfo = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModules);
|
clanModulesFileInfo = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModules);
|
||||||
clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes);
|
clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes);
|
||||||
|
clanModulesMeta = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesMeta);
|
||||||
|
|
||||||
# Simply evaluated options (JSON)
|
# Simply evaluated options (JSON)
|
||||||
renderOptions =
|
renderOptions =
|
||||||
@ -54,6 +55,7 @@
|
|||||||
# A file that contains the links to all clanModule docs
|
# A file that contains the links to all clanModule docs
|
||||||
export CLAN_MODULES=${clanModulesFileInfo}
|
export CLAN_MODULES=${clanModulesFileInfo}
|
||||||
export CLAN_MODULES_READMES=${clanModulesReadmes}
|
export CLAN_MODULES_READMES=${clanModulesReadmes}
|
||||||
|
export CLAN_MODULES_META=${clanModulesMeta}
|
||||||
|
|
||||||
mkdir $out
|
mkdir $out
|
||||||
|
|
||||||
|
@ -43,11 +43,16 @@ let
|
|||||||
module_name: _module: self.lib.modules.getReadme module_name
|
module_name: _module: self.lib.modules.getReadme module_name
|
||||||
) clanModules;
|
) clanModules;
|
||||||
|
|
||||||
|
clanModulesMeta = builtins.mapAttrs (
|
||||||
|
module_name: _module:
|
||||||
|
(self.lib.evalClanModules [ module_name ]).config.clan.${module_name}.meta or { }
|
||||||
|
) clanModules;
|
||||||
|
|
||||||
# clanCore docs
|
# clanCore docs
|
||||||
clanCoreDocs = (evalDocs (getOptions [ ]).clan.core).optionsJSON;
|
clanCoreDocs = (evalDocs (getOptions [ ]).clan.core).optionsJSON;
|
||||||
in
|
in
|
||||||
{
|
{
|
||||||
inherit clanModulesReadmes;
|
inherit clanModulesReadmes clanModulesMeta;
|
||||||
clanCore = clanCoreDocs;
|
clanCore = clanCoreDocs;
|
||||||
clanModules = clanModulesDocs;
|
clanModules = clanModulesDocs;
|
||||||
}
|
}
|
||||||
|
@ -32,6 +32,8 @@ from typing import Any
|
|||||||
CLAN_CORE = os.getenv("CLAN_CORE")
|
CLAN_CORE = os.getenv("CLAN_CORE")
|
||||||
CLAN_MODULES = os.environ.get("CLAN_MODULES")
|
CLAN_MODULES = os.environ.get("CLAN_MODULES")
|
||||||
CLAN_MODULES_READMES = os.environ.get("CLAN_MODULES_READMES")
|
CLAN_MODULES_READMES = os.environ.get("CLAN_MODULES_READMES")
|
||||||
|
CLAN_MODULES_META = os.environ.get("CLAN_MODULES_META")
|
||||||
|
|
||||||
|
|
||||||
OUT = os.environ.get("out")
|
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}"
|
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:
|
if not OUT:
|
||||||
raise ValueError(f"Environment variables are not set correctly: $out={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:
|
with open(CLAN_MODULES_READMES) as readme:
|
||||||
readme_map: dict[str, str] = json.load(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', ... }
|
# {'borgbackup': '/nix/store/hi17dwgy7963ddd4ijh81fv0c9sbh8sw-options.json', ... }
|
||||||
for module_name, options_file in links.items():
|
for module_name, options_file in links.items():
|
||||||
with open(Path(options_file) / "share/doc/nixos/options.json") as f:
|
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):
|
if readme_map.get(module_name, None):
|
||||||
output += f"{readme_map[module_name]}\n"
|
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 += module_usage(module_name)
|
||||||
|
|
||||||
output += options_head if len(options.items()) else ""
|
output += options_head if len(options.items()) else ""
|
||||||
|
Loading…
Reference in New Issue
Block a user