yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

ClanModules: Add docs and api to retrieve metadata

Browse Source
This commit is contained in:
Johannes Kirschbauer
2024-06-25 21:17:01 +02:00
parent 4022c13b31
commit 9b0e2a87e8
36 changed files with 342 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/nix/flake-module.nix
View File

@@ -18,8 +18,8 @@
};
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);
# clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes);
# clanModulesMeta = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesMeta);
# Simply evaluated options (JSON)
renderOptions =
@@ -30,6 +30,7 @@
nativeBuildInputs = [
pkgs.python3
pkgs.mypy
self'.packages.clan-cli
];
}
''
@@ -50,18 +51,25 @@
sha256 = "sha256-GZMeZFFGvP5GMqqh516mjJKfQaiJ6bL38bSYOXkaohc=";
};
module-docs = pkgs.runCommand "rendered" { nativeBuildInputs = [ pkgs.python3 ]; } ''
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}
export CLAN_MODULES_META=${clanModulesMeta}
module-docs =
pkgs.runCommand "rendered"
{
nativeBuildInputs = [
pkgs.python3
self'.packages.clan-cli
];
}
''
export CLAN_CORE_PATH=${self}
export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json
# A file that contains the links to all clanModule docs
export CLAN_MODULES=${clanModulesFileInfo}
mkdir $out
mkdir $out
# The python script will place mkDocs files in the output directory
python3 ${renderOptions}
'';
# The python script will place mkDocs files in the output directory
python3 ${renderOptions}
'';
in
{
devShells.docs = pkgs.callPackage ./shell.nix {

11
docs/nix/get-module-docs.nix
View File

@@ -3,7 +3,6 @@
pkgs,
clanCore,
clanModules,
self,
}:
let
allNixosModules = (import "${nixpkgs}/nixos/modules/module-list.nix") ++ [
@@ -39,20 +38,10 @@ let
name: module: (evalDocs ((getOptionsWithoutCore [ module ]).clan.${name} or { })).optionsJSON
) clanModules;
clanModulesReadmes = builtins.mapAttrs (
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 clanModulesMeta;
clanCore = clanCoreDocs;
clanModules = clanModulesDocs;
}

63
docs/nix/scripts/renderOptions.py
View File

@@ -28,12 +28,12 @@ import os
from pathlib import Path
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")
CLAN_MODULES_META = os.environ.get("CLAN_MODULES_META")
from clan_cli.api.modules import Frontmatter, extract_frontmatter, get_roles
# Get environment variables
CLAN_CORE_PATH = os.getenv("CLAN_CORE_PATH")
CLAN_CORE_DOCS = os.getenv("CLAN_CORE_DOCS")
CLAN_MODULES = os.environ.get("CLAN_MODULES")
OUT = os.environ.get("out")
@@ -124,7 +124,7 @@ def render_option(name: str, option: dict[str, Any], level: int = 3) -> str:
def module_header(module_name: str) -> str:
return f"# {module_name}\n"
return f"# {module_name}\n\n"
def module_usage(module_name: str) -> str:
@@ -150,9 +150,9 @@ options_head = "\n## Module Options\n"
def produce_clan_core_docs() -> None:
if not CLAN_CORE:
if not CLAN_CORE_DOCS:
raise ValueError(
f"Environment variables are not set correctly: $CLAN_CORE={CLAN_CORE}"
f"Environment variables are not set correctly: $CLAN_CORE_DOCS={CLAN_CORE_DOCS}"
)
if not OUT:
@@ -160,7 +160,7 @@ def produce_clan_core_docs() -> None:
# A mapping of output file to content
core_outputs: dict[str, str] = {}
with open(CLAN_CORE) as f:
with open(CLAN_CORE_DOCS) as f:
options: dict[str, dict[str, Any]] = json.load(f)
module_name = "clan-core"
for option_name, info in options.items():
@@ -192,13 +192,11 @@ def produce_clan_core_docs() -> None:
of.write(output)
def render_meta(meta: dict[str, Any], module_name: str) -> str:
roles = meta.get("availableRoles", None)
def render_roles(roles: list[str] | None, module_name: str) -> str:
if roles:
roles_list = "\n".join([f" - `{r}`" for r in roles])
return f"""
???+ tip "Inventory (WIP)"
???+ tip "Inventory usage"
Predefined roles:
@@ -226,14 +224,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 CLAN_MODULES_META:
if not CLAN_CORE_PATH:
raise ValueError(
f"Environment variables are not set correctly: $CLAN_MODULES_META={CLAN_MODULES_META}"
f"Environment variables are not set correctly: $CLAN_CORE_PATH={CLAN_CORE_PATH}"
)
if not OUT:
@@ -242,27 +236,36 @@ 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)
# 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)
# with open(CLAN_MODULES_META) as f:
# meta_map: dict[str, Any] = json.load(f)
# print(meta_map)
# {'borgbackup': '/nix/store/hi17dwgy7963ddd4ijh81fv0c9sbh8sw-options.json', ... }
for module_name, options_file in links.items():
readme_file = Path(CLAN_CORE_PATH) / "clanModules" / module_name / "README.md"
print(module_name, readme_file)
with open(readme_file) as f:
readme = f.read()
frontmatter: Frontmatter
frontmatter, readme_content = extract_frontmatter(readme, str(readme_file))
print(frontmatter, readme_content)
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"
if frontmatter.description:
output += f"**{frontmatter.description}**\n\n"
output += f"{readme_content}\n"
# Add meta information:
# - Inventory implementation status
if meta_map.get(module_name, None):
output += render_meta(meta_map.get(module_name, {}), module_name)
# get_roles(str) -> list[str] | None
roles = get_roles(str(Path(CLAN_CORE_PATH) / "clanModules" / module_name))
if roles:
output += render_roles(roles, module_name)
output += module_usage(module_name)