Merge pull request 'docs: move official services into subfolder' (#5369) from docs-simplify into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5369

docs/.gitignore

@@ -1,4 +1,5 @@
 /site/reference
+/site/services/official
 /site/static
 /site/options
 /site/openapi.json

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"
 

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

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)

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.
 
 ---