wrapper-manager-fds/docs: reorganize to make way for other docs output

Makefile

@@ -1,10 +1,10 @@
 .PHONY: docs-serve
 docs-serve:
-	hugo -s docs serve
+	hugo -s docs/website serve
 
 .PHONY: docs-build
 docs-build:
-	hugo -s docs
+	hugo -s docs/website
 
 # Ideally, this should be done only in the remote CI environment with a certain
 # update cadence/rhythm.

README.adoc

@@ -1 +1 @@
-docs/content/en/project-overview.adoc
+docs/website/content/en/project-overview.adoc

docs/.gitignore

@@ -1,22 +1,3 @@
-# All of the generated assets.
-/content/*/nix-module-options/*/content.json
-
-### Hugo ###
-# Generated files by hugo
-/public/
-/resources/_gen/
-/assets/jsconfig.json
-hugo_stats.json
-
-# Executable may be added to repository
-hugo.exe
-hugo.darwin
-hugo.linux
-
-# Temporary lock file while building
-/.hugo_build.lock
-
-
 ### Ruby ###
 *.gem
 *.rbc

docs/README.adoc

@@ -0,0 +1,11 @@
+= Documentation
+:toc:
+
+This is where the documentation is created, namely both the website and the manual page.
+
+* The website is powered by Hugo and it is pretty much what makes most of the files here.
+It requires Hugo and whatever Hugo module feature requires so it isn't possible to build it offline.
+For now, we rely on the remote CI having network access for it (which is pretty much the standard for the most part so no worries there).
+
+* The manual page is powered by some under-documented tool in the Nix ecosystem (as is tradition) called https://github.com/NixOS/nixpkgs/tree/de19b7eaffd1ec24c50a6a257f3674a841ab1221/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs[nixos-render-docs].
+The adjacent tools in the Nix-module-options-doc-generation ecosystem are also what makes the (autogenerated) Nix module options pages found in the website.

docs/config/_default/menu.toml

@@ -1,9 +0,0 @@
-[[main]]
-identifier = "nix-module-options"
-name = "Module options"
-url = "nix-module-options/"
-
-[[main]]
-identifier = "source-code"
-name = "Source code"
-url = "https://github.com/foo-dogsquared/wrapper-manager-fds"

docs/default.nix

@@ -11,19 +11,40 @@ in
 
 let
   inherit (pkgs) nixosOptionsDoc stdenv lib;
+
+  # Pretty much inspired from home-manager's documentation build process.
+  evalDoc = args@{ modules, includeModuleSystemOptions ? false, ... }:
+    let
+      options = (pkgs.lib.evalModules {
+        modules = modules ++ [ { _module.check = false; } ];
+        class = "wrapperManager";
+      }).options;
+    in
+    nixosOptionsDoc ({
+      options =
+        if includeModuleSystemOptions
+        then options
+        else builtins.removeAttrs options [ "_module" ];
+      }
+      // builtins.removeAttrs args [ "modules" "includeModuleSystemOptions" ]);
   buildHugoSite = pkgs.callPackage ./hugo-build-module.nix { };
-  wrapperManagerLib = import ../lib/env.nix;
-
-  wrapperManagerEval = wrapperManagerLib.eval { inherit pkgs; };
-
-  optionsDoc = nixosOptionsDoc { inherit (wrapperManagerEval) options; };
 
+  wmOptionsDoc = evalDoc {
+    modules = [ ../modules/wrapper-manager ];
+    includeModuleSystemOptions = true;
+  };
+in
+{
+  website =
+    let
       gems = pkgs.bundlerEnv {
         name = "wrapper-manager-fds-gem-env";
         ruby = pkgs.ruby_3_1;
         gemdir = ./.;
       };
 
+      wrapperManagerLib = (import ../. { }).lib;
+
       # Now this is some dogfooding.
       asciidoctorWrapped =
         wrapperManagerLib.build {
@@ -39,20 +60,20 @@ let
             })
           ];
         };
-in
-buildHugoSite {
+    in
+    buildHugoSite {
       pname = "wrapper-manager-docs";
       version = "2024-07-13";
 
       src = lib.fileset.toSource {
         root = ./.;
         fileset = lib.fileset.unions [
-      ./assets
-      ./config
-      ./content
-      ./layouts
-      ./go.mod
-      ./go.sum
+          ./website/assets
+          ./website/config
+          ./website/content
+          ./website/layouts
+          ./website/go.mod
+          ./website/go.sum
         ];
       };
 
@@ -66,12 +87,6 @@ buildHugoSite {
         gems.wrappedRuby
       ];
 
-  installPhase = ''
-    runHook preInstall
-    cp --reflink=auto "$src/public" "$out"
-    runHook postInstall
-  '';
-
       meta = with lib; {
         description = "wrapper-manager-fds documentation";
         homepage = "https://github.com/foo-dogsquared/wrapper-manager-fds";
@@ -81,4 +96,18 @@ buildHugoSite {
         ];
         platforms = platforms.all;
       };
+    };
+
+  inherit wmOptionsDoc;
+  wmNixosDoc = evalDoc { modules = [ ../modules/env/nixos ];  };
+  wmHmDoc = evalDoc { modules = [ ../modules/env/home-manager ]; };
+
+  manualPage = pkgs.runCommand "wrapper-manager-reference-manpage" {
+    nativeBuildInputs = with pkgs; [ nixos-render-docs ];
+  } ''
+    mkdir -p $out/share/man/man5
+    nixos-render-docs options manpage \
+      ${wmOptionsDoc.optionsJSON}/share/doc/nixos/options.json \
+      $out/share/man/man5/wrapper-manager.nix.5
+  '';
 }

docs/shell.nix

@@ -1,25 +0,0 @@
-let
-  sources = import ../npins;
-in
-{ pkgs ? import sources.nixos-unstable { } }:
-
-let
-  inherit (pkgs) nixosOptionsDoc;
-  websitePkg = import ./. { inherit pkgs; };
-  wrapperManagerLib = import ../lib/env.nix;
-
-  wrapperManagerEval = wrapperManagerLib.eval { inherit pkgs; };
-  optionsDoc = nixosOptionsDoc { inherit (wrapperManagerEval) options; };
-in
-with pkgs; mkShell {
-  inputsFrom = [ websitePkg ];
-
-  packages = [
-    nodePackages.prettier
-    vscode-langservers-extracted
-  ];
-
-  shellHook = ''
-    install -Dm0644 ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./content/en-US/nix-module-options/module-environment/content.json
-  '';
-}

docs/website/.gitignore

@@ -0,0 +1,17 @@
+# All of the generated assets.
+/content/**/wrapper-manager-*.adoc
+
+### Hugo ###
+# Generated files by hugo
+/public/
+/resources/_gen/
+/assets/jsconfig.json
+hugo_stats.json
+
+# Executable may be added to repository
+hugo.exe
+hugo.darwin
+hugo.linux
+
+# Temporary lock file while building
+/.hugo_build.lock

docs/website/config/_default/menu.toml

@@ -0,0 +1,20 @@
+[[main]]
+identifier = "nix-module-options"
+name = "Module options"
+url = "wrapper-manager-env-options/"
+weight = 1
+
+[[main]]
+identifier = "source-code"
+name = "Source code"
+url = "https://github.com/foo-dogsquared/wrapper-manager-fds"
+
+[[main]]
+identifier = "wrapper-manager-nixos"
+name = "NixOS module"
+url = "wrapper-manager-nixos-module/"
+
+[[main]]
+identifier = "wrapper-manager-home-manager"
+name = "home-manager module"
+url = "wrapper-manager-home-manager-module/"

docs/website/shell.nix

@@ -0,0 +1,22 @@
+let
+  sources = import ../../npins;
+in
+{ pkgs ? import sources.nixos-unstable { } }:
+
+let
+  docs = import ../. { inherit pkgs; };
+in
+with pkgs; mkShell {
+  inputsFrom = [ docs.website ];
+
+  packages = [
+    nodePackages.prettier
+    vscode-langservers-extracted
+  ];
+
+  shellHook = ''
+    install -Dm0644 ${docs.wmOptionsDoc.optionsAsciiDoc} ./content/en/wrapper-manager-env-options.adoc
+    install -Dm0644 ${docs.wmNixosDoc.optionsAsciiDoc} ./content/en/wrapper-manager-nixos-module.adoc
+    install -Dm0644 ${docs.wmHmDoc.optionsAsciiDoc} ./content/en/wrapper-manager-home-manager-module.adoc
+  '';
+}