docs: refactor wrapper-options docs

nix-community · Oct 21, 2024 · 0562e51 · 0562e51
1 parent 5992a22
commit 0562e51
Show file tree

Hide file tree

Showing 6 changed files with 54 additions and 19 deletions.
diff --git a/docs/default.nix b/docs/default.nix
@@ -42,13 +42,6 @@ let
     ];
   };
 
-  hmOptions = builtins.removeAttrs (lib.evalModules {
-    modules = [
-      ../wrappers/modules/hm.nix
-      { _module.check = false; } # Ignore missing option declarations
-    ];
-  }).options [ "_module" ];
-
   options-json =
     (pkgs.nixosOptionsDoc {
       inherit (evaledModules) options;
@@ -83,7 +76,7 @@ in
     # Do not check if documentation builds fine on darwin as it fails:
     # > sandbox-exec: pattern serialization length 69298 exceeds maximum (65535)
     docs = pkgs.callPackage ./mdbook {
-      inherit evaledModules hmOptions transformOptions;
+      inherit evaledModules transformOptions;
       # TODO: Find how to handle stable when 24.11 lands
       search = mkSearch "/nixvim/search/";
     };

diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md
@@ -11,7 +11,7 @@
 
 # Platforms
 
-- [Home Manager Usage](./modules/hm.md)
+- [Platform-specific options](./modules/wrapper-options.md)
 - [Standalone Usage](./modules/standalone.md)
 
 # Options

diff --git a/docs/mdbook/default.nix b/docs/mdbook/default.nix
@@ -4,7 +4,6 @@
   evaledModules,
   nixosOptionsDoc,
   transformOptions,
-  hmOptions,
   search,
 }:
 let
@@ -227,6 +226,29 @@ let
     ) docs.modules;
   };
 
+  wrapperOptions =
+    lib.genAttrs
+      [
+        "hm"
+        "nixos"
+        "darwin"
+      ]
+      (
+        name:
+        let
+          configuration = lib.evalModules {
+            modules = [
+              ../../wrappers/modules/${name}.nix
+              {
+                # Ignore definitions for missing options
+                _module.check = false;
+              }
+            ];
+          };
+        in
+        removeUnwanted configuration.options
+      );
+
   prepareMD = ''
     # Copy inputs into the build directory
     cp -r --no-preserve=all $inputs/* ./
@@ -243,8 +265,10 @@ let
     substituteInPlace ./SUMMARY.md \
       --replace-fail "@NIXVIM_OPTIONS@" "$(cat ${pkgs.writeText "nixvim-options-summary.md" mdbook.nixvimOptions})"
 
-    substituteInPlace ./modules/hm.md \
-      --replace-fail "@HM_OPTIONS@" "$(cat ${mkMDDoc hmOptions})"
+    substituteInPlace ./modules/wrapper-options.md \
+      --replace-fail "@NIXOS_OPTIONS@" "$(cat ${mkMDDoc wrapperOptions.nixos})" \
+      --replace-fail "@HM_OPTIONS@" "$(cat ${mkMDDoc wrapperOptions.hm})" \
+      --replace-fail "@DARWIN_OPTIONS@" "$(cat ${mkMDDoc wrapperOptions.darwin})"
   '';
 in
 pkgs.stdenv.mkDerivation {

diff --git a/docs/modules/hm.md b/docs/modules/hm.md
diff --git a/docs/modules/wrapper-options.md b/docs/modules/wrapper-options.md
@@ -0,0 +1,24 @@
+# Platform-specific options
+
+All of Nixvim's options are available within `programs.nixvim.*` when Nixvim is used via wrapper modules,
+such as our NixOS, home-manager, or nix-darwin modules.
+
+When Nixvim is used standalone (without a wrapper module), its options are available at the "top-level".
+See [Standalone Usage](./standalone.md) for more info.
+
+There are a few wrapper specific options that are documented below:
+
+## NixOS
+
+@NIXOS_OPTIONS@
+
+## home-manager
+
+@HM_OPTIONS@
+
+## nix-darwin
+
+@DARWIN_OPTIONS@
+
+<!-- TODO: Add @STANDALONE_OPTIONS@ if we ever have standalone-specific options -->
+
diff --git a/docs/user-guide/install.md b/docs/user-guide/install.md
@@ -70,7 +70,7 @@ options as `programs.nixvim.<path>.<to>.<option> = <value>`.
 When you use nixvim as a module, an additional module argument is passed on allowing you to peek through the configuration with `hmConfig`, `nixosConfig`, and `darwinConfig` for home-manager, NixOS, and nix-darwin respectively.
 This is useful is you use nixvim both as part of an environment and as standalone.
 
-If using the home-manager module, see [Home Manager Usage](../modules/hm.md) for more information.
+For more information on module-specific options, see [Platform-specific options](../modules/wrapper-options.md).
 
 ### Standalone usage