From 9232d12f2508dab52119ce3da05e96c26bdfcb42 Mon Sep 17 00:00:00 2001
From: hylodon <forgejo-user@hylodon.uk>
Date: Sun, 1 Mar 2026 17:49:00 +0000
Subject: [PATCH] Added documentation about modules.

NixOS and Home Manager both automatically generate documentation using 'nixosOptionsDoc', and now so does hylonix.

I can't find any standard reference for where this documentation should go, so I have created a doc attribute in the flake.
---
 .gitignore       |  1 +
 docs/default.nix | 56 ++++++++++++++++++++++++++++++++++++++++++++++++
 flake.nix        |  2 ++
 3 files changed, 59 insertions(+)
 create mode 100644 docs/default.nix

diff --git a/.gitignore b/.gitignore
index 224ebf0..92221b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,5 +3,6 @@
 !.gitignore
 !flake.nix
 !flake.lock
+!docs/**/*.nix
 !lib/**.nix
 !modules/**/*.nix
diff --git a/docs/default.nix b/docs/default.nix
new file mode 100644
index 0000000..0e43095
--- /dev/null
+++ b/docs/default.nix
@@ -0,0 +1,56 @@
+{
+  pkgs,
+  lib,
+  self,
+  ...
+}:
+
+let
+  baseModule = _: {
+    # Hide documentation relating to _module.args, which isn't a part
+    # of this flake
+    options._module.args = lib.mkOption { internal = true; };
+    # Turn off the checks on the config. We only want the options, so
+    # don't eval the config.
+    config._module.check = false;
+  };
+
+  makeModuleDocs =
+    subcomponent: modules:
+    let
+      eval = lib.evalModules {
+        modules = [ baseModule ] ++ modules;
+        class = "hylonix";
+        specialArgs = { inherit pkgs lib; };
+      };
+      docs = pkgs.buildPackages.nixosOptionsDoc {
+        inherit (eval) options;
+        warningsAreErrors = false;
+      };
+    in
+    {
+      # These formats are generated by nixosOptionsDoc,
+      # so may as well expose them.
+      asciiDoc = docs.optionsAsciiDoc;
+      commonMark = docs.optionsCommonMark;
+      json = docs.optionsJSON;
+      nix = docs.optionsNix;
+    };
+in
+{
+  modules = {
+    all = makeModuleDocs "modules" (
+      builtins.attrValues self.hmModules ++ builtins.attrValues self.nixosModules
+    );
+
+    hm = {
+      all = makeModuleDocs "hmModules" (builtins.attrValues self.hmModules);
+      module = builtins.mapAttrs (k: v: makeModuleDocs "hmModules-${k}" [ v ]) self.hmModules;
+    };
+
+    nixos = {
+      all = makeModuleDocs "nixosModules" (builtins.attrValues self.nixosModules);
+      module = builtins.mapAttrs (k: v: makeModuleDocs "nixosModules-${k}" [ v ]) self.nixosModules;
+    };
+  };
+}
diff --git a/flake.nix b/flake.nix
index 1d66787..63ca6c7 100644
--- a/flake.nix
+++ b/flake.nix
@@ -11,6 +11,8 @@
       forAllSystems = nixos.lib.genAttrs nixos.lib.systems.flakeExposed;
     in
     {
+      docs = forAllSystems (system: nixos.legacyPackages.${system}.callPackage ./docs { inherit self; });
+
       formatter = forAllSystems (system: nixos.legacyPackages.${system}.nixfmt-tree);
 
       hmModules = import ./modules/home-manager self.lib.hylonix;