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,74 +11,103 @@ 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; };
+  wmOptionsDoc = evalDoc {
-
+    modules = [ ../modules/wrapper-manager ];
-  optionsDoc = nixosOptionsDoc { inherit (wrapperManagerEval) options; };
+    includeModuleSystemOptions = true;
-
-  gems = pkgs.bundlerEnv {
-    name = "wrapper-manager-fds-gem-env";
-    ruby = pkgs.ruby_3_1;
-    gemdir = ./.;
   };
-
-  # Now this is some dogfooding.
-  asciidoctorWrapped =
-    wrapperManagerLib.build {
-      inherit pkgs;
-      modules = [
-        ({ config, lib, pkgs, ... }: {
-          wrappers.asciidoctor = {
-            arg0 = lib.getExe' gems "asciidoctor";
-            appendArgs = [
-              "-T" "${sources.website}/templates"
-            ];
-          };
-        })
-      ];
-    };
 in
-buildHugoSite {
+{
-  pname = "wrapper-manager-docs";
+  website =
-  version = "2024-07-13";
+    let
+      gems = pkgs.bundlerEnv {
+        name = "wrapper-manager-fds-gem-env";
+        ruby = pkgs.ruby_3_1;
+        gemdir = ./.;
+      };
 
-  src = lib.fileset.toSource {
+      wrapperManagerLib = (import ../. { }).lib;
-    root = ./.;
-    fileset = lib.fileset.unions [
-      ./assets
-      ./config
-      ./content
-      ./layouts
-      ./go.mod
-      ./go.sum
-    ];
-  };
 
-  vendorHash = "sha256-vMLi8of2eF/s60B/lM3FDfSntEyieGkvJbTSMuI7Wws=";
+      # Now this is some dogfooding.
+      asciidoctorWrapped =
+        wrapperManagerLib.build {
+          inherit pkgs;
+          modules = [
+            ({ config, lib, pkgs, ... }: {
+              wrappers.asciidoctor = {
+                arg0 = lib.getExe' gems "asciidoctor";
+                appendArgs = [
+                  "-T" "${sources.website}/templates"
+                ];
+              };
+            })
+          ];
+        };
+    in
+    buildHugoSite {
+      pname = "wrapper-manager-docs";
+      version = "2024-07-13";
 
-  buildInputs = with pkgs; [
+      src = lib.fileset.toSource {
-    asciidoctorWrapped
+        root = ./.;
-    hugo
+        fileset = lib.fileset.unions [
-    git
+          ./website/assets
-    gems
+          ./website/config
-    gems.wrappedRuby
+          ./website/content
-  ];
+          ./website/layouts
+          ./website/go.mod
+          ./website/go.sum
+        ];
+      };
 
-  installPhase = ''
+      vendorHash = "sha256-vMLi8of2eF/s60B/lM3FDfSntEyieGkvJbTSMuI7Wws=";
-    runHook preInstall
+
-    cp --reflink=auto "$src/public" "$out"
+      buildInputs = with pkgs; [
-    runHook postInstall
+        asciidoctorWrapped
+        hugo
+        git
+        gems
+        gems.wrappedRuby
+      ];
+
+      meta = with lib; {
+        description = "wrapper-manager-fds documentation";
+        homepage = "https://github.com/foo-dogsquared/wrapper-manager-fds";
+        license = with licenses; [
+          mit
+          fdl13Only
+        ];
+        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
   '';
-
-  meta = with lib; {
-    description = "wrapper-manager-fds documentation";
-    homepage = "https://github.com/foo-dogsquared/wrapper-manager-fds";
-    license = with licenses; [
-      mit
-      fdl13Only
-    ];
-    platforms = platforms.all;
-  };
 }

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
+  '';
+}