docs: use `nixosOptionsDoc`

Output is mostly unchanged aside from some minor typographical and
formatting changes, along with better source links.

We temporarily export `options.docBookForMigration` to allow
`nix-doc-munge` to check its conversions.

default.nix

@@ -1,7 +1,11 @@
 { pkgs ? import <nixpkgs> { } }:
 
 rec {
-  docs = with import ./docs { inherit pkgs; }; {
+  docs = let releaseInfo = pkgs.lib.importJSON ./release.json;
+  in with import ./docs {
+    inherit pkgs;
+    inherit (releaseInfo) release isReleaseBranch;
+  }; {
     html = manual.html;
     manPages = manPages;
     json = options.json;

docs/default.nix

@@ -1,7 +1,9 @@
 { pkgs
 
 # Note, this should be "the standard library" + HM extensions.
-, lib ? import ../modules/lib/stdlib-extended.nix pkgs.lib }:
+, lib ? import ../modules/lib/stdlib-extended.nix pkgs.lib
+
+, release, isReleaseBranch }:
 
 let
 
@@ -11,7 +13,16 @@ let
     sha256 = "0vvj40k6bw8ssra8wil9rqbsznmfy1kwy7cihvm13rajwdg9ycgg";
   };
 
-  nmd = import nmdSrc { inherit lib pkgs; };
+  nmd = import nmdSrc {
+    inherit lib;
+    # The DocBook output of `nixos-render-docs` doesn't have the change
+    # `nmd` uses to work around the broken stylesheets in
+    # `docbook-xsl-ns`, so we restore the patched version here.
+    pkgs = pkgs // {
+      docbook-xsl-ns =
+        pkgs.docbook-xsl-ns.override { withManOptDedupPatch = true; };
+    };
+  };
 
   # Make sure the used package is scrubbed to avoid actually
   # instantiating derivations.
@@ -26,42 +37,67 @@ let
 
   dontCheckDefinitions = { _module.check = false; };
 
-  buildModulesDocs = args:
-    nmd.buildModulesDocs ({
-      moduleRootPaths = [ ./.. ];
-      mkModuleUrl = path:
-        "https://github.com/nix-community/home-manager/blob/master/${path}#blob-path";
-      channelName = "home-manager";
-    } // args);
+  gitHubDeclaration = user: repo: subpath:
+    let urlRef = if isReleaseBranch then "release-${release}" else "master";
+    in {
+      url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}";
+      name = "<${repo}/${subpath}>";
+    };
 
-  hmModulesDocs = buildModulesDocs {
+  hmPath = toString ./..;
+
+  buildOptionsDocs = args@{ modules, ... }:
+    pkgs.buildPackages.nixosOptionsDoc ({
+      options = (lib.evalModules { inherit modules; }).options;
+      warningsAreErrors = false;
+      transformOptions = opt:
+        opt // {
+          # Clean up declaration sites to not refer to the Home Manager
+          # source tree.
+          declarations = map (decl:
+            if lib.hasPrefix hmPath (toString decl) then
+              gitHubDeclaration "nix-community" "home-manager"
+              (lib.removePrefix "/" (lib.removePrefix hmPath (toString decl)))
+            else if decl == "lib/modules.nix" then
+            # TODO: handle this in a better way (may require upstream
+            # changes to nixpkgs)
+              gitHubDeclaration "NixOS" "nixpkgs" decl
+            else
+              decl) opt.declarations;
+        };
+    } // builtins.removeAttrs args [ "modules" ]);
+
+  hmOptionsDocs = buildOptionsDocs {
     modules = import ../modules/modules.nix {
       inherit lib pkgs;
       check = false;
     } ++ [ scrubbedPkgsModule ];
-    docBook.id = "home-manager-options";
+    variablelistId = "home-manager-options";
   };
 
-  nixosModuleDocs = buildModulesDocs {
+  nixosOptionsDocs = buildOptionsDocs {
     modules = [ ../nixos scrubbedPkgsModule dontCheckDefinitions ];
-    docBook = {
-      id = "nixos-options";
-      optionIdPrefix = "nixos-opt";
-    };
+    variablelistId = "nixos-options";
+    optionIdPrefix = "nixos-opt-";
   };
 
-  nixDarwinModuleDocs = buildModulesDocs {
+  nixDarwinOptionsDocs = buildOptionsDocs {
     modules = [ ../nix-darwin scrubbedPkgsModule dontCheckDefinitions ];
-    docBook = {
-      id = "nix-darwin-options";
-      optionIdPrefix = "nix-darwin-opt";
-    };
+    variablelistId = "nix-darwin-options";
+    optionIdPrefix = "nix-darwin-opt-";
   };
 
   docs = nmd.buildDocBookDocs {
     pathName = "home-manager";
     projectName = "Home Manager";
-    modulesDocs = [ hmModulesDocs nixDarwinModuleDocs nixosModuleDocs ];
+    modulesDocs = [{
+      docBook = pkgs.linkFarm "hm-module-docs-for-nmd" {
+        "nmd-result/home-manager-options.xml" = hmOptionsDocs.optionsDocBook;
+        "nmd-result/nix-darwin-options.xml" =
+          nixDarwinOptionsDocs.optionsDocBook;
+        "nmd-result/nixos-options.xml" = nixosOptionsDocs.optionsDocBook;
+      };
+    }];
     documentsDirectory = ./.;
     documentType = "book";
     chunkToc = ''
@@ -81,9 +117,29 @@ in {
   inherit nmdSrc;
 
   options = {
-    json = hmModulesDocs.json.override {
-      path = "share/doc/home-manager/options.json";
-    };
+    # TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream
+    # `nixosOptionsDoc` is more customizable.
+    json = pkgs.runCommand "options.json" {
+      meta.description = "List of Home Manager options in JSON format";
+    } ''
+      mkdir -p $out/{share/doc,nix-support}
+      cp -a ${hmOptionsDocs.optionsJSON}/share/doc/nixos $out/share/doc/home-manager
+      substitute \
+        ${hmOptionsDocs.optionsJSON}/nix-support/hydra-build-products \
+        $out/nix-support/hydra-build-products \
+        --replace \
+          '${hmOptionsDocs.optionsJSON}/share/doc/nixos' \
+          "$out/share/doc/home-manager"
+    '';
+
+    # Temporary export for Markdown migration.
+    docBookForMigration = pkgs.runCommand "hm-docbook-for-migration" { } ''
+      cat \
+        ${hmOptionsDocs.optionsDocBook} \
+        ${nixDarwinOptionsDocs.optionsDocBook} \
+        ${nixosOptionsDocs.optionsDocBook} \
+        > $out
+    '';
   };
 
   manPages = docs.manPages;

docs/man-configuration.xml

@@ -26,7 +26,7 @@
    You can use the following options in
    <filename>home-configuration.nix</filename>:
   </para>
-  <xi:include href="./nmd-result/home-manager-options.xml" />
+  <xi:include href="./nmd-result/home-manager-options.xml" xpointer="home-manager-options" />
  </refsection>
  <refsection>
    <title>See also</title>

docs/manual.xml

@@ -39,15 +39,15 @@
  <xi:include href="faq.xml" />
  <appendix xml:id="ch-options">
   <title>Configuration Options</title>
-  <xi:include href="./nmd-result/home-manager-options.xml" />
+  <xi:include href="./nmd-result/home-manager-options.xml" xpointer="home-manager-options" />
  </appendix>
  <appendix xml:id="ch-nixos-options">
   <title>NixOS Module Options</title>
-  <xi:include href="./nmd-result/nixos-options.xml" />
+  <xi:include href="./nmd-result/nixos-options.xml" xpointer="nixos-options" />
  </appendix>
  <appendix xml:id="ch-nix-darwin-options">
   <title>nix-darwin Module Options</title>
-  <xi:include href="./nmd-result/nix-darwin-options.xml" />
+  <xi:include href="./nmd-result/nix-darwin-options.xml" xpointer="nix-darwin-options" />
  </appendix>
  <appendix xml:id="ch-tools">
   <title>Tools</title>

flake.nix

@@ -105,7 +105,11 @@
       packages = forAllSystems (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
-          docs = import ./docs { inherit pkgs; };
+          releaseInfo = nixpkgs.lib.importJSON ./release.json;
+          docs = import ./docs {
+            inherit pkgs;
+            inherit (releaseInfo) release isReleaseBranch;
+          };
           hmPkg = pkgs.callPackage ./home-manager { path = toString ./.; };
         in {
           default = hmPkg;

modules/manual.nix

@@ -6,7 +6,10 @@ let
 
   cfg = config.manual;
 
-  docs = import ../docs { inherit lib pkgs; };
+  docs = import ../docs {
+    inherit pkgs lib;
+    inherit (config.home.version) release isReleaseBranch;
+  };
 
 in {
   options = {