docs: move wrapper options to dedicated sub-pages

nix-community · Oct 24, 2024 · 4726334 · 4726334
1 parent 131e74e
commit 4726334
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 52 deletions.
diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md
@@ -12,6 +12,7 @@
 # Platforms
 
 - [Nixvim Platforms](./platforms/index.md)
+@PLATFORM_OPTIONS@
 	- [Standalone](./platforms/standalone.md)
 
 # Options

diff --git a/docs/mdbook/default.nix b/docs/mdbook/default.nix
@@ -225,58 +225,48 @@ let
       "${padding}- [${name}](${path})"
     ) docs.modules;
 
-    wrapperOptionFiles = lib.mapAttrs' (name: options: {
-      name = options.meta.wrapper.name.value;
-      # TODO:
-      # value.path = "./platforms/${name}.md";
-      value.file = mkMDDoc options;
-    }) wrapperOptions;
-
-    wrapperOptionDocs =
-      pkgs.runCommandNoCCLocal "wrapper-option-doc"
-        {
-          __structuredAttrs = true;
-          files = lib.mapAttrs (name: value: value.file) mdbook.wrapperOptionFiles;
-          # TODO:
-          # paths = lib.mapAttrs (name: value: value.path) mdbook.wrapperOptionFiles;
-        }
-        ''
-          for name in "''${!files[@]}"
-          do
-            # $file contains the docs built by mkMDDoc
-            file="''${files[$name]}"
-            # TODO: consider putting wrapper docs in separate files:
-            # path="''${paths[$name]}"
-            echo >> "$out"
-            echo "## $name" >> "$out"
-            echo >> "$out"
-            cat "$file" >> $out
-          done
-        '';
-  };
-
-  wrapperOptions =
-    lib.genAttrs
-      [
-        "hm"
-        "nixos"
-        "darwin"
-      ]
-      (
-        name:
-        let
+    # A list of platform-specific docs
+    # [ { name, file, path, configuration } ]
+    wrapperOptions =
+      builtins.map
+        (filename: rec {
+          # Eval a configuration for the platform's module
           configuration = lib.evalModules {
             modules = [
-              ../../wrappers/modules/${name}.nix
+              ../../wrappers/modules/${filename}.nix
               {
                 # Ignore definitions for missing options
                 _module.check = false;
               }
             ];
           };
-        in
-        removeUnwanted configuration.options
-      );
+          # Also include display name, filepath, and rendered docs
+          inherit (configuration.config.meta.wrapper) name;
+          file = mkMDDoc (removeUnwanted configuration.options);
+          path = "./platforms/${filename}.md";
+        })
+        [
+          "nixos"
+          "hm"
+          "darwin"
+        ];
+
+    # Markdown summary for the table of contents
+    wrapperOptionsSummary = lib.foldl (
+      text: { name, path, ... }: text + "\n\t- [${name}](${path})"
+    ) "" mdbook.wrapperOptions;
+
+    # Attrset of { filePath = renderedDocs; }
+    wrapperOptionsFiles = lib.listToAttrs (
+      builtins.map (
+        { path, file, ... }:
+        {
+          name = path;
+          value = file;
+        }
+      ) mdbook.wrapperOptions
+    );
+  };
 in
 
 pkgs.stdenv.mkDerivation (finalAttrs: {
@@ -324,23 +314,31 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     # Copy the generated MD docs into the build directory
     bash -e ${finalAttrs.passthru.copy-docs}
 
+    # Copy the generated MD docs for the wrapper options
+    for path in "''${!wrapperOptionsFiles[@]}"
+    do
+      file="''${wrapperOptionsFiles[$path]}"
+      cp "$file" "$path"
+    done
+
     # Patch SUMMARY.md - which defiens mdBook's table of contents
     substituteInPlace ./SUMMARY.md \
+      --replace-fail "@PLATFORM_OPTIONS@" "$wrapperOptionsSummary" \
       --replace-fail "@NIXVIM_OPTIONS@" "$nixvimOptionsSummary"
 
-    substituteInPlace ./platforms/index.md \
-      --replace-fail "@WRAPPER_OPTIONS@" "$(cat ${finalAttrs.passthru.wrapperOptionDocs})"
-
     mdbook build
     cp -r ./book/* $dest
     mkdir -p $dest/search
     cp -r ${search}/* $dest/search
   '';
 
-  inherit (mdbook) nixvimOptionsSummary;
+  inherit (mdbook)
+    nixvimOptionsSummary
+    wrapperOptionsSummary
+    wrapperOptionsFiles
+    ;
 
   passthru = {
-    inherit (mdbook) wrapperOptionDocs;
     copy-docs = pkgs.writeShellScript "copy-docs" docs.commands;
   };
 })
diff --git a/docs/platforms/index.md b/docs/platforms/index.md
@@ -6,7 +6,5 @@ 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:
-
-@WRAPPER_OPTIONS@
+There are a few wrapper specific options, which are documented in their respective sub-pages.