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,13 +81,13 @@ 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:
+          - Overview: reference/clanModules/index.md
-              - 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
@@ -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:
+      - NixOS Modules:
-          - reference/clan-core/index.md
+          - clan.core:
+              - Overview: reference/clan.core/index.md
 
-          - reference/clan-core/backups.md
+              - reference/clan.core/backups.md
-          - reference/clan-core/deployment.md
+              - reference/clan.core/deployment.md
-          - reference/clan-core/facts.md
+              - reference/clan.core/facts.md
-          - reference/clan-core/networking.md
+              - reference/clan.core/networking.md
-          - reference/clan-core/settings.md
+              - reference/clan.core/settings.md
-          - reference/clan-core/sops.md
+              - reference/clan.core/sops.md
-          - reference/clan-core/state.md
+              - reference/clan.core/state.md
-          - reference/clan-core/vars.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,17 +297,29 @@ 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] = (
+        core_outputs[indexfile] = module_header(module_name) + clan_core_descr
-            module_header(module_name) + clan_core_descr + options_head
+
+        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"
             print(
@@ -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
 
 ---

pkgs/clan-cli/clan_cli/__init__.py

@@ -119,7 +119,7 @@ def create_parser(prog: str | None = None) -> argparse.ArgumentParser:
         description="The clan cli tool",
         epilog=(
             f"""
-Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli/")}
+Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli")}
 For more detailed information, visit: {help_hyperlink("docs", "https://docs.clan.lol")}
         """
         ),
@@ -171,7 +171,7 @@ Examples:
   The backup to restore for the machine [MACHINE] with the configured [PROVIDER]
   with the name [NAME].
 
-For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/getting-started/backups")}.
+For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/guides/backups")}.
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -190,7 +190,7 @@ Examples:
   Will create a new clan flake in the specified directory and create it if it
   doesn't exist yet. The flake will be created from a default template.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/index.html")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -208,7 +208,7 @@ Examples:
   $ clan flash write mymachine --disk main /dev/sd<X> --ssh-pubkey ~/.ssh/id_rsa.pub
   Will flash the machine 'mymachine' to the disk '/dev/sd<X>' with the ssh public key '~/.ssh/id_rsa.pub'.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started/installer")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/installer")}
             """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -235,7 +235,7 @@ Examples:
   the json string. [JSON] can either be a json formatted string itself, or point
   towards a file containing the deployment information
 
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/deploy")}
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -259,7 +259,7 @@ Examples:
   $ clan secrets get [SECRET]
   Will display the content of the specified secret.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -296,7 +296,7 @@ Examples:
   This is especially useful for resetting certain passwords while leaving the rest
   of the facts for a machine in place.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -334,7 +334,7 @@ Examples:
     This is especially useful for resetting certain passwords while leaving the rest
     of the vars for a machine in place.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -364,7 +364,7 @@ Examples:
   If the `--target-host` flag is omitted will try to find host information by
   checking the deployment configuration inside the specified machine.
 
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/deploy")}
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -427,7 +427,7 @@ Examples:
   $ clan state list [MACHINE]
   List state of the machines managed by Clan.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/backups")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/backups")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,

pkgs/clan-cli/clan_cli/facts/cli.py

@@ -31,7 +31,7 @@ Examples:
   Will check facts for the specified machine.
 
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -61,7 +61,7 @@ Examples:
   Will list facts for the specified machine.
 
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -101,7 +101,7 @@ Examples:
   This is especially useful for resetting certain passwords while leaving the rest
   of the facts for a machine in place.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -125,7 +125,7 @@ Examples:
   $ clan facts upload [MACHINE]
   Will upload secrets to a specific machine.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,

pkgs/clan-cli/clan_cli/hyperlink.py

@@ -37,4 +37,7 @@ def docs_hyperlink(description: str, url: str) -> str:
     """
     Returns a markdown hyperlink
     """
+    url = url.replace("https://docs.clan.lol", "../..")
+    url = url.replace("index.html", "index")
+    url += ".md"
     return f"[{description}]({url})"

pkgs/clan-cli/clan_cli/machines/cli.py

@@ -37,7 +37,7 @@ Examples:
   To exclude machines being updated `clan.deployment.requireExplicitUpdate = true;`
   can be set in the machine config.
 
-For more detailed information, visit: https://docs.clan.lol/getting-started/deploy
+For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -93,7 +93,7 @@ Examples:
   $ clan machines update-hardware-config [MACHINE] [TARGET_HOST]
   Will generate hardware specifics for the the specified `[TARGET_HOST]` and place the result in hardware.nix for the given machine `[MACHINE]`.
 
-For more detailed information, visit: https://docs.clan.lol/getting-started/configure/#machine-configuration
+For more detailed information, visit: https://docs.clan.lol/guides/getting-started/configure/#machine-configuration
 
 """
         ),
@@ -123,8 +123,8 @@ Examples:
   Will install the specified machine [MACHINE] to the host exposed by
   the deployment information of the [JSON] deployment string.
 
-For information on how to set up the installer see: https://docs.clan.lol/getting-started/installer/
+For information on how to set up the installer see: https://docs.clan.lol/guides/getting-started/installer/
-For more detailed information, visit: https://docs.clan.lol/getting-started/deploy
+For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,

pkgs/clan-cli/clan_cli/machines/machines.py

@@ -93,7 +93,7 @@ class Machine:
             msg = f"'targetHost' is not set for machine '{self.name}'"
             raise ClanError(
                 msg,
-                description="See https://docs.clan.lol/getting-started/deploy/#setting-the-target-host for more information.",
+                description="See https://docs.clan.lol/guides/getting-started/deploy/#setting-the-target-host for more information.",
             )
         return val
 

pkgs/clan-cli/clan_cli/state/__init__.py

@@ -29,7 +29,7 @@ def register_parser(parser: argparse.ArgumentParser) -> None:
   List state of the machine [MACHINE] managed by Clan.
 
 
-  For more detailed information, visit: https://docs.clan.lol/getting-started/backups/
+  For more detailed information, visit: https://docs.clan.lol/guides/backups
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,

pkgs/clan-cli/clan_cli/vars/cli.py

@@ -197,7 +197,7 @@ Examples:
   $ clan vars upload [MACHINE]
   Will upload secrets to a specific machine.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,

templates/clan/flake-parts/flake.nix

@@ -19,7 +19,7 @@
         "aarch64-darwin"
       ];
       imports = [ inputs.clan-core.flakeModules.default ];
-      # https://docs.clan.lol/getting-started/flake-parts/
+      # https://docs.clan.lol/guides/getting-started/flake-parts/
       clan = {
         meta.name = "__CHANGE_ME__"; # Ensure this is unique among all clans you want to use.
 

templates/clan/new-clan/flake.nix

@@ -14,7 +14,7 @@
         # All machines in ./machines will be imported.
 
         # Prerequisite: boot into the installer.
-        # See: https://docs.clan.lol/getting-started/installer
+        # See: https://docs.clan.lol/guides/getting-started/installer
         # local> mkdir -p ./machines/machine1
         # local> Edit ./machines/<machine>/configuration.nix to your liking.
         machines = {