From 9ed72a85ab1ac1f605d97dc64952adc7af3b44c8 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 4 Aug 2025 12:03:37 +0200
Subject: [PATCH] nixos/documentation/modular-services: init

Render documentation for modular services.
https://nixos.org/manual/nixos/unstable/#modular-services

This is admittedly not a great solution, but it is a rather simple
solution that we can use until we develop a proper one.

Flaws:
- These are rendered in the NixOS documentation, but modular services
  are not meant to be exclusive to NixOS.
- They are rendered as NixOS options, but should be imported into
  service submodules.

Benefits:
- Simple
- search.nixos.org integration for free
---
 .../misc/documentation/modular-services.nix   | 31 +++++++++++++++++++
 nixos/modules/module-list.nix                 |  1 +
 2 files changed, 32 insertions(+)
 create mode 100644 nixos/modules/misc/documentation/modular-services.nix

diff --git a/nixos/modules/misc/documentation/modular-services.nix b/nixos/modules/misc/documentation/modular-services.nix
new file mode 100644
index 000000000000..07de80689658
--- /dev/null
+++ b/nixos/modules/misc/documentation/modular-services.nix
@@ -0,0 +1,31 @@
+/**
+  Renders documentation for modular services.
+  For inclusion into documentation.nixos.extraModules.
+*/
+{ lib, pkgs, ... }:
+let
+  /**
+    Causes a modular service's docs to be rendered.
+    This is an intermediate solution until we have "native" service docs in some nicer form.
+  */
+  fakeSubmodule =
+    module:
+    lib.mkOption {
+      type = lib.types.submoduleWith {
+        modules = [ module ];
+      };
+      description = "This is a [modular service](https://nixos.org/manual/nixos/unstable/#modular-services), which can be imported into a NixOS configuration using the [`system.services`](https://search.nixos.org/options?channel=unstable&show=system.services&query=modular+service) option.";
+    };
+
+  modularServicesModule = {
+    _file = "${__curPos.file}:${toString __curPos.line}";
+    options = {
+      "<imports = [ pkgs.ghostunnel.services.default ]>" = fakeSubmodule pkgs.ghostunnel.services.default;
+    };
+  };
+in
+{
+  documentation.nixos.extraModules = [
+    modularServicesModule
+  ];
+}
diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index eb52b87a22b5..38881059011b 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -139,6 +139,7 @@
   ./misc/assertions.nix
   ./misc/crashdump.nix
   ./misc/documentation.nix
+  ./misc/documentation/modular-services.nix
   ./misc/extra-arguments.nix
   ./misc/ids.nix
   ./misc/label.nix