Merge pull request 'Refactor(docs): consistent structure across references & fix broken cli links' (#3724) from hsjobeki/clan-core:docs-3 into main

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

docs/mkdocs.yml

@@ -81,14 +81,14 @@ nav:
   - Reference:
       - Overview: reference/index.md
       - Clan Services:
-          - reference/clanServices/index.md
+          - Overview: reference/clanServices/index.md
           - reference/clanServices/admin.md
           - reference/clanServices/hello-world.md
           - reference/clanServices/wifi.md
       - Clan Modules:
-          - Overview:
-              - reference/clanModules/index.md
-              - reference/clanModules/frontmatter/index.md
+          - Overview: reference/clanModules/index.md
+          - Frontmatter Format: reference/clanModules/frontmatter/index.md
+          - reference/clanModules/frontmatter/index.md
           # TODO: display the docs of the clan.service modules
           - reference/clanModules/admin.md
           # This is the module overview and should stay at the top
@@ -132,7 +132,7 @@ nav:
           - reference/clanModules/zerotier.md
           - reference/clanModules/zt-tcp-relay.md
       - CLI:
-          - reference/cli/index.md
+          - Overview: reference/cli/index.md
 
           - reference/cli/backups.md
           - reference/cli/facts.md
@@ -146,17 +146,18 @@ nav:
           - reference/cli/state.md
           - reference/cli/vars.md
           - reference/cli/vms.md
-      - Clan Core:
-          - reference/clan-core/index.md
+      - NixOS Modules:
+          - clan.core:
+              - Overview: reference/clan.core/index.md
 
-          - reference/clan-core/backups.md
-          - reference/clan-core/deployment.md
-          - reference/clan-core/facts.md
-          - reference/clan-core/networking.md
-          - reference/clan-core/settings.md
-          - reference/clan-core/sops.md
-          - reference/clan-core/state.md
-          - reference/clan-core/vars.md
+              - reference/clan.core/backups.md
+              - reference/clan.core/deployment.md
+              - reference/clan.core/facts.md
+              - reference/clan.core/networking.md
+              - reference/clan.core/settings.md
+              - reference/clan.core/sops.md
+              - reference/clan.core/state.md
+              - reference/clan.core/vars.md
       - Nix API:
           - buildClan: reference/nix-api/buildclan.md
           - Inventory: reference/nix-api/inventory.md

docs/nix/render_options/__init__.py

@@ -206,7 +206,12 @@ Some modules are considered 'low-level' or 'expert modules' and are not availabl
 """
 
 
-clan_core_descr = """`clan.core` is always included in each machine `config`.
+clan_core_descr = """
+`clan.core` is always present in a clan machine
+
+* It is a module of class **`nixos`**
+* Provides a set of common options for every machine (in addition to the NixOS options)
+
 Your can customize your machines behavior with the configuration [options](#module-options) provided below.
 """
 
@@ -292,16 +297,28 @@ def produce_clan_core_docs() -> None:
     core_outputs: dict[str, str] = {}
     with CLAN_CORE_DOCS.open() as f:
         options: dict[str, dict[str, Any]] = json.load(f)
-        module_name = "clan-core"
+        module_name = "clan.core"
 
         transform = {n.replace("clan.core.", ""): v for n, v in options.items()}
         split = split_options_by_root(transform)
 
         # Prepopulate the index file header
         indexfile = f"{module_name}/index.md"
-        core_outputs[indexfile] = (
-            module_header(module_name) + clan_core_descr + options_head
-        )
+        core_outputs[indexfile] = module_header(module_name) + clan_core_descr
+
+        core_outputs[indexfile] += """!!! info "Submodules"\n"""
+
+        for submodule_name, split_options in split.items():
+            root = options_to_tree(split_options, debug=True)
+            module = root.suboptions[0]
+            module_type = module.info.get("type")
+            if module_type is not None and "submodule" not in module_type:
+                continue
+            core_outputs[indexfile] += (
+                f"      - [{submodule_name}](./{submodule_name}.md)\n"
+            )
+
+        core_outputs[indexfile] += options_head
 
         for submodule_name, split_options in split.items():
             outfile = f"{module_name}/{submodule_name}.md"
@@ -317,7 +334,6 @@ def produce_clan_core_docs() -> None:
             print("type", module.info.get("type"))
 
             module_type = module.info.get("type")
-
             if module_type is not None and "submodule" not in module_type:
                 outfile = indexfile
                 init_level = 2

docs/site/guides/getting-started/secrets.md

@@ -3,7 +3,7 @@ Clan enables encryption of secrets (such as passwords & keys) ensuring security
 
 By default, Clan uses the [sops](https://github.com/getsops/sops) format
 and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
-Clan can also be configured to be used with other secret store [backends](https://docs.clan.lol/reference/clan-core/vars/#clan.core.vars.settings.secretStore).
+Clan can also be configured to be used with other secret store [backends](../../reference/clan.core/vars.md#clan.core.vars.settings.secretStore).
 
 This guide will walk you through:
 

docs/site/guides/migrations/migration-facts-vars.md

@@ -5,7 +5,7 @@ For a high level overview about `vars` see our [blog post](https://clan.lol/blog
 This guide will help you migrate your modules that still use our [`facts`](../../guides/secrets.md) backend
 to the [`vars`](../../guides/vars-backend.md) backend.
 
-The `vars` [module](../../reference/clan-core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
+The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
 
 ## Keep Existing Values
 

docs/site/guides/vars-backend.md

@@ -7,7 +7,7 @@ Defining a linux user's password via the nixos configuration previously required
 
 In this example, we will guide you through automating that interaction using clan `vars`.
 
-For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](https://docs.clan.lol/reference/clan-core/vars/)
+For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](../reference/clan.core/vars.md)
 
 This guide assumes
 - clan is set up already (see [Getting Started](../guides/getting-started/index.md))
@@ -147,5 +147,5 @@ Updated var root-password/password-hash
 
 ## Further Reading
 
-- [Reference Documentation for `clan.core.vars` nixos options](../reference/clan-core/vars.md)
+- [Reference Documentation for `clan.core.vars` nixos options](../reference/clan.core/vars.md)
 - [Reference Documentation for the `clan vars` cli command](../reference/cli/vars.md)

docs/site/index.md

@@ -70,7 +70,7 @@ hide:
 
     An overview of available service modules
 
--   [Core](./reference/clan-core/index.md)
+-   [Core](./reference/clan.core/index.md)
 
     ---
 

docs/site/reference/index.md

@@ -6,7 +6,7 @@ This section of the site provides an overview of available options and commands
 
 - Learn how to use the [Clan CLI](./cli/index.md)
 - Explore available services and application [modules](./clanModules/index.md)
-- Discover [configuration options](./clan-core/index.md) that manage essential features
+- Discover [configuration options](./clan.core/index.md) that manage essential features
 - Find descriptions of the [Nix interfaces](./nix-api/buildclan.md) for defining a Clan
 
 ---