From 95b565eada3b511d02165444bd79a86b81e9a5b4 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 8 Oct 2024 14:22:16 +0200
Subject: [PATCH] Docs: init module author guide

---
 docs/mkdocs.yml                |   2 +
 docs/site/clanmodules/index.md | 124 +++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index cb7805dba..bbf6832d3 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -30,6 +30,8 @@ markdown_extensions:
       use_pygments: true
       anchor_linenums: true
   - pymdownx.keys
+  - pymdownx.snippets:
+      base_path: ../.
   - toc:
       title: On this page
 
diff --git a/docs/site/clanmodules/index.md b/docs/site/clanmodules/index.md
index 844de7d91..430df9a40 100644
--- a/docs/site/clanmodules/index.md
+++ b/docs/site/clanmodules/index.md
@@ -5,3 +5,127 @@ This site will guide you through authoring your first module. Explaining which c
 :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
 Under construction
 :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
+
+## Bootstrapping a `clanModule`
+
+A ClanModule is a specific subset of a [NixOS Module](https://nix.dev/tutorials/module-system/index.html), but it has some constraints and might be used via the [Inventory](../manual/inventory.md) interface.
+
+Because ClanModules should be configurable via `json` all of its interface (`options`) must be serializable.
+
+Currently ClanModules should be contributed to the [clan-core repository](https://git.clan.lol/clan/clan-core). Ad-hoc loading of custom modules is not recommended / supported yet.
+
+!!! Tip
+    ClanModules interface can be checked by running the json schema converter as follows.
+
+    `nix build .#legacyPackages.x86_64-linux.schemas.inventory`
+
+    If the build succeeds the module is compatible.
+
+## Directory structure
+
+Each module SHOULD be a directory of the following format:
+
+```sh
+# Example: borgbackup
+clanModules/borgbackup
+├── README.md
+└── roles
+    ├── client.nix
+    └── server.nix
+```
+
+!!! Tip
+    This format is strictly required for `features = [ "inventory" ]`.
+    Some module authors might decide to opt-out of [inventory](../manual/inventory.md) usage.
+
+The next step is to register the module via the `clanModules` attribute.
+
+!!! Note
+    Currently ClanModules should be contributed to the clan-core repository. Ad-hoc loading modules is not recommended / supported yet.
+
+```nix title="clanModules/flake-module.nix"
+--8<-- "clanModules/flake-module.nix:0:6"
+    # Register your new module here
+    # ...
+```
+
+## Readme
+
+The `README.md` is a required file. It MUST contain frontmatter in [`toml`]() format.
+
+```markdown
+---
+description = "Module A"
+---
+
+This is the example module that does xyz.
+```
+
+See the [frontmatter reference](#frontmatter-reference) for all supported attributes.
+
+## Roles
+
+Each `.nix` file in the `roles` directory is added as a role to the service.
+
+Other files can be placed alongside the `.nix` files
+
+```sh
+└── roles
+    ├── client.nix
+    └── server.nix
+```
+
+Adds the roles: `client` and `server`
+
+## Organizing the ClanModule
+
+Each `{role}.nix` is included into the machine if the machine is declared to have the role.
+
+For example
+
+```nix
+roles.client.machines = ["MachineA"];
+```
+
+Then `roles/client.nix` will be added to the machine `MachineA`.
+
+## Frontmatter Reference
+
+`description` (**Required** `String`)
+:   Short description of the module
+
+`categories` (Optional `[ String ]`)
+:   default `[ "Uncategorized" ]`
+
+    Categories are used for Grouping and searching.
+
+    While initial oriented on [freedesktop](https://specifications.freedesktop.org/menu-spec/latest/category-registry.html) the following categories are allowed
+
+    - AudioVideo
+    - Audio
+    - Video
+    - Development
+    - Education
+    - Game
+    - Graphics
+    - Social
+    - Network
+    - Office
+    - Science
+    - System
+    - Settings
+    - Utility
+    - Uncategorized
+
+`features` (Optional `[ String ]`)
+:   default `[]`
+
+    Clans Features that the module implements support for.
+
+    Available feature flags are:
+
+    - `inventory`
+
+    !!! warning "Important"
+        Every ClanModule, that specifies `features = [ "inventory" ]` MUST have at least one role.
+        Many modules use `roles/default.nix` which registers the role `default`