From 59b933653ab2ba7b7976cbb8b4b134a7363edf6f Mon Sep 17 00:00:00 2001 From: Emily Date: Wed, 28 Jun 2023 22:55:00 +0100 Subject: [PATCH] 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 | 6 ++- docs/default.nix | 106 ++++++++++++++++++++++++++++--------- docs/man-configuration.xml | 2 +- docs/manual.xml | 6 +-- flake.nix | 6 ++- modules/manual.nix | 5 +- 6 files changed, 99 insertions(+), 32 deletions(-) diff --git a/default.nix b/default.nix index b665b7a66..541a5a388 100644 --- a/default.nix +++ b/default.nix @@ -1,7 +1,11 @@ { pkgs ? import { } }: 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; diff --git a/docs/default.nix b/docs/default.nix index fb51a7517..393e94b6e 100644 --- a/docs/default.nix +++ b/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; diff --git a/docs/man-configuration.xml b/docs/man-configuration.xml index ce35feb78..a7d1f5119 100644 --- a/docs/man-configuration.xml +++ b/docs/man-configuration.xml @@ -26,7 +26,7 @@ You can use the following options in home-configuration.nix: - + See also diff --git a/docs/manual.xml b/docs/manual.xml index 22cfd970e..af757caf8 100644 --- a/docs/manual.xml +++ b/docs/manual.xml @@ -39,15 +39,15 @@ Configuration Options - + NixOS Module Options - + nix-darwin Module Options - + Tools diff --git a/flake.nix b/flake.nix index c0bc1ee75..8267cb740 100644 --- a/flake.nix +++ b/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; diff --git a/modules/manual.nix b/modules/manual.nix index 356f311a9..b7abdcf19 100644 --- a/modules/manual.nix +++ b/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 = {