From 86ee7e24e53a08456911ff1e686745bd947fa0eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Sun, 30 Jun 2024 14:58:33 +0200
Subject: [PATCH] docs/darwin: document current modules

---
 docs/darwin/mixins.md | 13 +++++++++++++
 docs/darwin/type.md   | 32 ++++++++++++++++++++++++++++++++
 mkdocs.yml            | 25 +++++++++++++++----------
 3 files changed, 60 insertions(+), 10 deletions(-)
 create mode 100644 docs/darwin/mixins.md
 create mode 100644 docs/darwin/type.md

diff --git a/docs/darwin/mixins.md b/docs/darwin/mixins.md
new file mode 100644
index 00000000..81bd1536
--- /dev/null
+++ b/docs/darwin/mixins.md
@@ -0,0 +1,13 @@
+Config extensions for a given machine.
+
+One or more can be included per NixOS configuration.
+
+### `darwiModules.mixins-telegraf`
+
+Enables a generic telegraf configuration. `nixosModules.mixins-prometheus` for monitoring rules targeting this telegraf configuration.
+
+### `darwinModules.mixins-terminfo`
+
+Extends the terminfo database with often used terminal emulators.
+Terminfo is used by terminal applications to interfere supported features in the terminal.
+This is useful when connecting to a server via SSH.
diff --git a/docs/darwin/type.md b/docs/darwin/type.md
new file mode 100644
index 00000000..b527ee64
--- /dev/null
+++ b/docs/darwin/type.md
@@ -0,0 +1,32 @@
+Those high-level modules are used to define the type of machine.
+
+We expect only one of those to be imported per Darwin configuration.
+
+### Common (`darwinModules.common`)
+
+Use this module if you are unsure if your darwin module will be used on server or desktop.
+
+- Better nix-daemon defaults
+- Better serial console support
+- Colored package diffs on nixos-rebuild
+- Use systemd in initrd by default and networkd as a backend for the
+  Networking module
+- Do not block on networkd/networkmanager's online target
+- Better zfs defaults
+- Add ssh host keys to well-known Git servers (eg: github)
+- Enable sudo for @wheel users.
+- ...
+
+### Server (`darwinModules.server`)
+
+Use this for headless systems that are remotely managed via ssh.
+
+- Includes everything from common
+- So far nothing else, but this might change over time
+
+### Desktop (`darwinModules.desktop`)
+
+Despite this project being about servers, we wanted to dogfood the common module.
+
+- Includes everything from common
+- So far nothing else, but this might change over time
diff --git a/mkdocs.yml b/mkdocs.yml
index 16bab199..6d426ac5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -17,14 +17,19 @@ nav:
   - Getting started: getting_started.md
   - User guide:
     - Intro: user_guide.md
-    - NixOS modules:
-      - Machine type: nixos/type.md
-      - Machine hardware: nixos/hardware.md
-      - Machine role: nixos/role.md
-      - Configuration mixins: nixos/mixins.md
-    - Roles:
-      - GitHub Action Runner: github_actions_runner.md
-    - Installation:
-        - Hetzner Cloud: installation/hetzner_cloud.md
+    - NixOS:
+      - Modules:
+        - Machine type: nixos/type.md
+        - Machine hardware: nixos/hardware.md
+        - Machine role: nixos/role.md
+        - Configuration mixins: nixos/mixins.md
+      - Roles:
+        - GitHub Action Runner: github_actions_runner.md
+      - Installation:
+          - Hetzner Cloud: installation/hetzner_cloud.md
+    - Nix-darwin:
+      - Modules:
+        - Machine type: darwin/type.md
+        - Configuration mixins: darwin/mixins.md
     - FAQ: faq.md
-  - Getting help: help.md
\ No newline at end of file
+  - Getting help: help.md