From 028cf2a00c1027b41b8e73051804d19c53d1ce59 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Fri, 3 Oct 2025 17:56:47 +0200 Subject: [PATCH] docs: move official services into subfolder --- docs/.gitignore | 1 + docs/mkdocs.yml | 55 ++++++++++--------- docs/nix/default.nix | 6 +- docs/nix/render_options/__init__.py | 16 +++--- docs/site/reference/index.md | 6 +- .../index.md => services/community.md} | 0 6 files changed, 44 insertions(+), 40 deletions(-) rename docs/site/{community/services/index.md => services/community.md} (100%) diff --git a/docs/.gitignore b/docs/.gitignore index 5d02a552e..3f1c155ae 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,4 +1,5 @@ /site/reference +/site/services/official /site/static /site/options /site/openapi.json diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 22f361890..a0308e8d0 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -108,8 +108,6 @@ nav: - Clan Options: reference/options/clan.md - Clan Inventory Options: reference/options/clan_inventory.md - - Clan Service API: reference/clanServices/clan-service-author-interface.md - - clan.core (Machine Options): - Overview: reference/clan.core/index.md - reference/clan.core/backups.md @@ -139,6 +137,8 @@ nav: - reference/cli/vars.md - reference/cli/vms.md + - Clan Service API: reference/clan-service-author-interface.md + - HTTP API: api.md - Decisions: @@ -151,32 +151,33 @@ nav: - decisions/template.md - Glossary: reference/glossary.md - Services: - - Introduction to ClanServices: reference/clanServices/index.md + - Introduction to ClanServices: services/official/index.md + # Generated list from the list of official services - Official: - - reference/clanServices/admin.md - - reference/clanServices/borgbackup.md - - reference/clanServices/certificates.md - - reference/clanServices/coredns.md - - reference/clanServices/data-mesher.md - - reference/clanServices/dyndns.md - - reference/clanServices/emergency-access.md - - reference/clanServices/garage.md - - reference/clanServices/hello-world.md - - reference/clanServices/importer.md - - reference/clanServices/localbackup.md - - reference/clanServices/matrix-synapse.md - - reference/clanServices/mycelium.md - - reference/clanServices/monitoring.md - - reference/clanServices/packages.md - - reference/clanServices/sshd.md - - reference/clanServices/syncthing.md - - reference/clanServices/trusted-nix-caches.md - - reference/clanServices/users.md - - reference/clanServices/wifi.md - - reference/clanServices/wireguard.md - - reference/clanServices/yggdrasil.md - - reference/clanServices/zerotier.md - - Community: community/services/index.md + - services/official/admin.md + - services/official/borgbackup.md + - services/official/certificates.md + - services/official/coredns.md + - services/official/data-mesher.md + - services/official/dyndns.md + - services/official/emergency-access.md + - services/official/garage.md + - services/official/hello-world.md + - services/official/importer.md + - services/official/localbackup.md + - services/official/matrix-synapse.md + - services/official/mycelium.md + - services/official/monitoring.md + - services/official/packages.md + - services/official/sshd.md + - services/official/syncthing.md + - services/official/trusted-nix-caches.md + - services/official/users.md + - services/official/wifi.md + - services/official/wireguard.md + - services/official/yggdrasil.md + - services/official/zerotier.md + - services/community.md - Search Clan Options: "/options" diff --git a/docs/nix/default.nix b/docs/nix/default.nix index ed717273b..271f48d99 100644 --- a/docs/nix/default.nix +++ b/docs/nix/default.nix @@ -44,13 +44,13 @@ pkgs.stdenv.mkDerivation { pushd docs mkdir -p ./site/reference/cli - cp -af ${module-docs}/* ./site/reference/ + cp -af ${module-docs}/services/* ./site/services/ + cp -af ${module-docs}/reference/* ./site/reference/ cp -af ${clan-cli-docs}/* ./site/reference/cli/ - mkdir -p ./site/reference/internal cp -af ${clan-lib-openapi} ./site/openapi.json - chmod -R +w ./site/reference + chmod -R +w ./site echo "Generated API documentation in './site/reference/' " rm -rf ./site/options diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index 7ede55c15..af622711f 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -273,8 +273,10 @@ def produce_clan_core_docs() -> None: core_outputs[outfile] += output for outfile, output in core_outputs.items(): - (Path(OUT) / outfile).parent.mkdir(parents=True, exist_ok=True) - with (Path(OUT) / outfile).open("w") as of: + (Path(OUT) / "reference" / outfile).parent.mkdir( + parents=True, exist_ok=True + ) + with (Path(OUT) / "reference" / outfile).open("w") as of: of.write(output) @@ -307,7 +309,7 @@ def produce_clan_service_docs() -> None: msg = f"Environment variables are not set correctly: $out={OUT}" raise ClanError(msg) - indexfile = Path(OUT) / "clanServices/index.md" + indexfile = Path(OUT) / "services/official" / "index.md" indexfile.parent.mkdir( parents=True, exist_ok=True, @@ -368,7 +370,7 @@ Learn how to use `clanServices` in practice in the [Using clanServices guide](/g replace_prefix=f"clan.{module_name}", ) - outfile = Path(OUT) / f"clanServices/{module_name}.md" + outfile = Path(OUT) / "services/official" / f"{module_name}.md" outfile.parent.mkdir( parents=True, exist_ok=True, @@ -437,7 +439,7 @@ Typically needed by module authors to define roles, behavior and metadata for di # for option in options_tree.suboptions: output += options_docs_from_tree(options_tree, init_level=2) - outfile = Path(OUT) / "clanServices/clan-service-author-interface.md" + outfile = Path(OUT) / "reference" / "clan-service-author-interface.md" outfile.parent.mkdir(parents=True, exist_ok=True) with Path.open(outfile, "w") as of: of.write(output) @@ -479,7 +481,7 @@ It can be set via the `inventory` attribute of the [`clan`](/reference/options/c for option in inventory_opt.suboptions: output += options_docs_from_tree(option, init_level=2) - outfile = Path(OUT) / "options/clan_inventory.md" + outfile = Path(OUT) / "reference/options" / "clan_inventory.md" outfile.parent.mkdir(parents=True, exist_ok=True) with Path.open(outfile, "w") as of: of.write(output) @@ -515,7 +517,7 @@ or via the [`clan`](/reference/options/clan.md) attribute of flake-parts. continue output += options_docs_from_tree(option, init_level=2) - outfile = Path(OUT) / "options/clan.md" + outfile = Path(OUT) / "reference/options" / "clan.md" outfile.parent.mkdir(parents=True, exist_ok=True) with Path.open(outfile, "w") as of: of.write(output) diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md index 72a7d81a5..41742feb6 100644 --- a/docs/site/reference/index.md +++ b/docs/site/reference/index.md @@ -5,9 +5,9 @@ This section of the site provides an overview of available options and commands --- - [Clan Configuration Option](/options) - for defining a Clan -- Learn how to use the [Clan CLI](./cli/index.md) -- Explore available [services](./clanServices/index.md) -- [NixOS Configuration Options](./clan.core/index.md) - Additional options avilable on a NixOS machine. +- Learn how to use the [Clan CLI](/reference/cli/index.md) +- Explore available [services](/services/index.md) +- [NixOS Configuration Options](/reference/clan.core/index.md) - Additional options avilable on a NixOS machine. --- diff --git a/docs/site/community/services/index.md b/docs/site/services/community.md similarity index 100% rename from docs/site/community/services/index.md rename to docs/site/services/community.md