docs: add reference index pages

- add index pages for each reference documentation category
- move concepts pages into the reference hierarchy
- render clanModules overview page in the style of the CLI overview

docs/.gitignore

@@ -1,3 +1,5 @@
-/site/reference
+/site/reference/clan-core
+/site/reference/clanModules
+/site/reference/cli
 /site/static/Roboto-Regular.ttf
 /site/static/FiraCode-VF.ttf

docs/mkdocs.yml

@@ -50,11 +50,10 @@ nav:
       - Mesh VPN: getting-started/mesh-vpn.md
       - Backup & Restore: getting-started/backups.md
       - Flake-parts: getting-started/flake-parts.md
-  - Concepts:
-      - Configuration: concepts/configuration.md
-      - Inventory: concepts/inventory.md
   - Reference:
+      - reference/index.md
       - Clan Modules:
+          - reference/clanModules/index.md
           - reference/clanModules/borgbackup-static.md
           - reference/clanModules/borgbackup.md
           - reference/clanModules/deltachat.md
@@ -79,13 +78,13 @@ nav:
           - reference/clanModules/zerotier-static-peers.md
           - reference/clanModules/zt-tcp-relay.md
       - CLI:
+          - reference/cli/index.md
           - reference/cli/backups.md
           - reference/cli/config.md
           - reference/cli/facts.md
           - reference/cli/flakes.md
           - reference/cli/flash.md
           - reference/cli/history.md
-          - reference/cli/index.md
           - reference/cli/machines.md
           - reference/cli/secrets.md
           - reference/cli/show.md
@@ -100,6 +99,10 @@ nav:
           - reference/clan-core/state.md
           - reference/clan-core/deployment.md
           - reference/clan-core/networking.md
+      - Nix API:
+          - reference/nix-api/index.md
+          - buildClan: reference/nix-api/buildclan.md
+          - Inventory: reference/nix-api/inventory.md
   - Contributing: contributing/contributing.md
 
 docs_dir: site

docs/nix/scripts/renderOptions.py

@@ -220,6 +220,11 @@ def render_roles(roles: list[str] | None, module_name: str) -> str:
     return ""
 
 
+clan_modules_descr = """Clan modules are [NixOS modules](https://wiki.nixos.org/wiki/NixOS_modules) which have been enhanced with additional features provided by Clan, with certain option types restricted to enable configuration through a graphical interface.
+
+"""
+
+
 def produce_clan_modules_docs() -> None:
     if not CLAN_MODULES:
         raise ValueError(
@@ -245,6 +250,12 @@ def produce_clan_modules_docs() -> None:
     #     print(meta_map)
 
     # {'borgbackup': '/nix/store/hi17dwgy7963ddd4ijh81fv0c9sbh8sw-options.json', ... }
+
+    modules_index = "# Modules Overview\n\n"
+    modules_index += clan_modules_descr
+    modules_index += "## Overview\n\n"
+    modules_index += '<div class="grid cards" markdown>\n\n'
+
     for module_name, options_file in links.items():
         readme_file = Path(CLAN_CORE_PATH) / "clanModules" / module_name / "README.md"
         print(module_name, readme_file)
@@ -254,6 +265,8 @@ def produce_clan_modules_docs() -> None:
             frontmatter, readme_content = extract_frontmatter(readme, str(readme_file))
             print(frontmatter, readme_content)
 
+        modules_index += build_option_card(module_name, frontmatter)
+
         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}...")
@@ -282,6 +295,39 @@ def produce_clan_modules_docs() -> None:
             with open(outfile, "w") as of:
                 of.write(output)
 
+    modules_index += "</div>"
+    modules_index += "\n"
+    modules_outfile = Path(OUT) / "clanModules/index.md"
+
+    with open(modules_outfile, "w") as of:
+        of.write(modules_index)
+
+
+def build_option_card(module_name: str, frontmatter: Frontmatter) -> str:
+    """
+    Build the overview index card for each reference target option.
+    """
+
+    def indent_all(text: str, indent_size: int = 4) -> str:
+        """
+        Indent all lines in a string.
+        """
+        indent = " " * indent_size
+        lines = text.split("\n")
+        indented_text = indent + ("\n" + indent).join(lines)
+        return indented_text
+
+    def to_md_li(module_name: str, frontmatter: Frontmatter) -> str:
+        md_li = (
+            f"""-   **[{module_name}](./{"-".join(module_name.split(" "))}.md)**\n\n"""
+        )
+        md_li += f"""{indent_all("---", 4)}\n\n"""
+        fmd = f"\n{frontmatter.description.strip()}" if frontmatter.description else ""
+        md_li += f"""{indent_all(fmd, 4)}"""
+        return md_li
+
+    return f"{to_md_li(module_name, frontmatter)}\n\n"
+
 
 if __name__ == "__main__":
     produce_clan_core_docs()

docs/site/concepts/configuration.md

@@ -1,56 +0,0 @@
-# Configuration
-
-## Introduction
-
-When managing machine configuration this can be done through many possible ways.
-Ranging from writing `nix` expression in a `flake.nix` file; placing `autoincluded` files into your machine directory; or configuring everything in a simple UI (upcomming).
-
-clan currently offers the following methods to configure machines:
-
-!!! Success "Recommended for nix people"
-
-    - flake.nix (i.e. via `buildClan`)
-        - `machine` argument
-        - `inventory` argument
-
-    - machines/`machine_name`/configuration.nix (`autoincluded` if it exists)
-
-???+ Note "Used by CLI & UI"
-
-    - inventory.json
-    - machines/`machine_name`/hardware-configuration.nix (`autoincluded` if it exists)
-
-
-!!! Warning "Deprecated"
-
-    machines/`machine_name`/settings.json
-
-## BuildClan
-
-The core function that produces a clan. It returns a set of consistent configurations for all machines with ready-to-use secrets, backups and other services.
-
-### Inputs
-
-`directory`
-: The directory containing the machines subdirectory
-
-`machines`
-: Allows to include machine-specific modules i.e. machines.${name} = { ... }
-
-`meta`
-: An optional set
-
-: `{ name :: string, icon :: string, description :: string }`
-
-`inventory`
-: Service set for easily configuring distributed services, such as backups
-
-: For more details see [Inventory](./inventory.md)
-
-`specialArgs`
-: Extra arguments to pass to nixosSystem i.e. useful to make self available
-
-`pkgsForSystem`
-: A function that maps from architecture to pkgs, if specified this nixpkgs will be only imported once for each system.
-  This improves performance, but all nipxkgs.* options will be ignored.
-  `(string -> pkgs )`

docs/site/concepts/inventory.md

@@ -1,206 +0,0 @@
-# Inventory
-
-`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
-
-## Meta
-
-Metadata about the clan, will be displayed upfront in the upcomming clan-app, make sure to choose a unique name.
-
-```{.nix hl_lines="3-8"}
-buildClan {
-    inventory = {
-        meta = {
-            # The following options are available
-            # name:        string # Required, name of the clan.
-            # description: null | string
-            # icon:        null | string
-        };
-    };
-}
-```
-
-## Machines
-
-Machines and a small pieve of their configuration can be added via `inventory.machines`.
-
-!!! Note
-    It doesn't matter where the machine gets introduced to buildClan - All delarations are valid, duplications are merged.
-
-    However the clan-app (UI) will create machines in the inventory, because it cannot create arbitrary nixos configs.
-
-In the following example `backup_server` is one machine - it may specify parts of its configuration in different places.
-
-```{.nix hl_lines="3-5 12-20"}
-buildClan {
-    machines = {
-        "backup_server" = {
-            # Any valid nixos config
-        };
-        "jon" = {
-            # Any valid nixos config
-        };
-    };
-    inventory = {
-        machines = {
-            "backup_server" = {
-                # Don't include any nixos config here
-                # The following fields are avilable
-                # description: null | string
-                # icon:        null | string
-                # name:        string
-                # system:      null | string
-                # tags:        [...string]
-            };
-            "jon" = {
-                # Same as above
-            };
-        };
-    };
-}
-```
-
-## Services
-
-### Available clanModules
-
-Currently the inventory interface is implemented by the following clanModules
-
-- [borgbackup](../reference/clanModules/borgbackup.md)
-- [packages](../reference/clanModules/packages.md)
-- [single-disk](../reference/clanModules/single-disk.md)
-
-See the respective module documentation for available roles.
-
-### Adding services to machines
-
-A module can be added to one or multiple machines via `Roles`. clan's `Role` interface provide sane defaults for a module this allows the module author to reduce the configuration overhead to a minimum.
-
-Each service can still be customized and configured according to the modules options.
-
-- Per instance configuration via `services.<serviceName>.<instanceName>.config`
-- Per machine configuration via `services.<serviceName>.<instanceName>.machines.<machineName>.config`
-
-### Configuration Examples
-
-!!! Example "Borgbackup Example"
-
-    To configure a service it needs to be added to the machine.
-    It is required to assign the service (`borgbackup`) an arbitrary instance name. (`instance_1`)
-
-    See also: [Multiple Service Instances](#multiple-service-instances)
-
-    ```{.nix hl_lines="14-17"}
-    buildClan {
-        inventory = {
-            machines = {
-                "backup_server" = {
-                    # Don't include any nixos config here
-                    # See inventory.Machines for available options
-                };
-                "jon" = {
-                    # Don't include any nixos config here
-                    # See inventory.Machines for available options
-                };
-            };
-            services = {
-                borgbackup.instance_1 = {
-                    roles.client.machines = [ "jon" ];
-                    roles.server.machines = [ "backup_server" ];
-                };
-            };
-        };
-    }
-    ```
-
-!!! Example "Packages Example"
-
-    This example shows how to add `pkgs.firefox` via the inventory interface.
-
-    ```{.nix hl_lines="8-11"}
-    buildClan {
-        inventory = {
-            machines = {
-                "sara" = {};
-                "jon" = {};
-            };
-            services = {
-                packages.set_1 = {
-                    roles.default.machines = [ "jon" "sara" ];
-                    # Packages is a configuration option of the "packages" clanModule
-                    config.packages = ["firefox"];
-                };
-            };
-        };
-    }
-    ```
-
-### Tags
-
-It is possible to add services to multiple machines via tags. The service instance gets added in the specified role. In this case `role = "default"`
-
-!!! Example "Tags Example"
-
-    ```{.nix hl_lines="5 8 13"}
-    buildClan {
-        inventory = {
-            machines = {
-                "sara" = {
-                    tags = ["browsing"];
-                };
-                "jon" = {
-                    tags = ["browsing"];
-                };
-            };
-            services = {
-                packages.set_1 = {
-                    roles.default.tags = [ "browsing" ];
-                    config.packages = ["firefox"];
-                };
-            };
-        };
-    }
-    ```
-
-### Multiple Service Instances
-
-!!! danger "Important"
-    Not all modules support multiple instances yet.
-
-Some modules have support for adding multiple instances of the same service in different roles or configurations.
-
-!!! Example
-
-    In this example `backup_server` has role `client` and `server` in different instances.
-
-    ```{.nix hl_lines="11 14"}
-    buildClan {
-        inventory = {
-            machines = {
-                "jon" = {};
-                "backup_server" = {};
-                "backup_backup_server" = {}
-            };
-            services = {
-                borgbackup.instance_1 = {
-                    roles.client.machines = [ "jon" ];
-                    roles.server.machines = [ "backup_server" ];
-                };
-                borgbackup.instance_1 = {
-                    roles.client.machines = [ "backup_server" ];
-                    roles.server.machines = [ "backup_backup_server" ];
-                };
-            };
-        };
-    }
-    ```
-
-### Schema specification
-
-The complete schema specification can be retrieved via:
-
-```sh
-nix build git+https://git.clan.lol/clan/clan-core#inventory-schema
-> result
-> ├── schema.cue
-> └── schema.json
-```

docs/site/getting-started/configure.md

@@ -1,5 +1,31 @@
 # Configuration - How to configure clan with your own machines
 
+Managing machine configurations can be done in the following ways:
+
+- writing `nix` expressions in a `flake.nix` file,
+- placing `autoincluded` files into your machine directory,
+- configuring everything in a simple UI (upcoming).
+
+Clan currently offers the following methods to configure machines:
+
+!!! Success "Recommended for nix people"
+
+    - flake.nix (i.e. via `buildClan`)
+        - `machine` argument
+        - `inventory` argument
+
+    - machines/`machine_name`/configuration.nix (`autoincluded` if it exists)
+
+???+ Note "Used by CLI & UI"
+
+    - inventory.json
+    - machines/`machine_name`/hardware-configuration.nix (`autoincluded` if it exists)
+
+
+!!! Warning "Deprecated"
+
+    machines/`machine_name`/settings.json
+
 ## Global configuration
 
 In the `flake.nix` file:

docs/site/reference/index.md

@@ -0,0 +1,8 @@
+# Documentation
+
+This section of the site contains information about the following topics:
+
+- How to use the [Clan CLI](./cli/index.md)
+- Available services and application [modules](./clanModules/index.md)
+- [Configuration options](./clan-core/index.md) controlling the essential features
+- Descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan

docs/site/reference/nix-api/buildclan.md

@@ -0,0 +1,29 @@
+# buildClan
+
+The core [function](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/default.nix) that produces a Clan. It returns a set of consistent configurations for all machines with ready-to-use secrets, backups and other services.
+
+## Inputs
+
+`directory`
+: The directory containing the machines subdirectory
+
+`machines`
+: Allows to include machine-specific modules i.e. machines.${name} = { ... }
+
+`meta`
+: An optional set
+
+: `{ name :: string, icon :: string, description :: string }`
+
+`inventory`
+: Service set for easily configuring distributed services, such as backups
+
+: For more details see [Inventory](./inventory.md)
+
+`specialArgs`
+: Extra arguments to pass to nixosSystem i.e. useful to make self available
+
+`pkgsForSystem`
+: A function that maps from architecture to pkgs, if specified this nixpkgs will be only imported once for each system.
+  This improves performance, but all nipxkgs.* options will be ignored.
+  `(string -> pkgs )`

docs/site/reference/nix-api/index.md

@@ -0,0 +1,6 @@
+# Nix API Overview
+
+There are two top-level components of the Nix API, which together allow for the declarative definition of a Clan:
+
+- the [Inventory](./inventory.md), a structure representing the machines, services, custom configurations, and other data that constitute a Clan, and
+- the [`buildClan`](./buildclan.md) function, which constructs a Clan from an Inventory definition.

docs/site/reference/nix-api/inventory.md

@@ -0,0 +1,57 @@
+# Inventory
+
+`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
+
+The following is the specification of the inventory in `cuelang`
+
+```cue
+{
+    meta: {
+        // A name of the clan (primarily shown by the UI)
+        name: string
+        // A description of the clan
+        description?: string
+        // The icon path
+        icon?: string
+    }
+
+    // A map of services
+    services: [string]: [string]: {
+        // Required meta fields
+        meta: {
+            name: string,
+            icon?: string
+            description?: string,
+        },
+        // Machines are added via the avilable roles
+        // Membership depends only on this field
+        roles: [string]: {
+            machines: [...string],
+            tags: [...string],
+        }
+        machines?: {
+            [string]: {
+                config?: {
+                    ...
+                }
+            }
+        },
+
+        // Global Configuration for the service
+        // Applied to all machines.
+        config?: {
+            // Schema depends on the module.
+            // It declares the interface how the service can be configured.
+            ...
+        }
+    }
+    // A map of machines, extends the machines of `buildClan`
+    machines: [string]: {
+        name: string,
+        description?: string,
+        icon?: string
+        tags: [...string]
+        system: string
+    }
+}
+```