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.
This commit is contained in:
Emily 2023-06-28 22:55:00 +01:00
parent 82c157f255
commit 59b933653a
6 changed files with 99 additions and 32 deletions

View file

@ -1,7 +1,11 @@
{ pkgs ? import <nixpkgs> { } }: { pkgs ? import <nixpkgs> { } }:
rec { 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; html = manual.html;
manPages = manPages; manPages = manPages;
json = options.json; json = options.json;

View file

@ -1,7 +1,9 @@
{ pkgs { pkgs
# Note, this should be "the standard library" + HM extensions. # 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 let
@ -11,7 +13,16 @@ let
sha256 = "0vvj40k6bw8ssra8wil9rqbsznmfy1kwy7cihvm13rajwdg9ycgg"; 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 # Make sure the used package is scrubbed to avoid actually
# instantiating derivations. # instantiating derivations.
@ -26,42 +37,67 @@ let
dontCheckDefinitions = { _module.check = false; }; dontCheckDefinitions = { _module.check = false; };
buildModulesDocs = args: gitHubDeclaration = user: repo: subpath:
nmd.buildModulesDocs ({ let urlRef = if isReleaseBranch then "release-${release}" else "master";
moduleRootPaths = [ ./.. ]; in {
mkModuleUrl = path: url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}";
"https://github.com/nix-community/home-manager/blob/master/${path}#blob-path"; name = "<${repo}/${subpath}>";
channelName = "home-manager"; };
} // args);
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 { modules = import ../modules/modules.nix {
inherit lib pkgs; inherit lib pkgs;
check = false; check = false;
} ++ [ scrubbedPkgsModule ]; } ++ [ scrubbedPkgsModule ];
docBook.id = "home-manager-options"; variablelistId = "home-manager-options";
}; };
nixosModuleDocs = buildModulesDocs { nixosOptionsDocs = buildOptionsDocs {
modules = [ ../nixos scrubbedPkgsModule dontCheckDefinitions ]; modules = [ ../nixos scrubbedPkgsModule dontCheckDefinitions ];
docBook = { variablelistId = "nixos-options";
id = "nixos-options"; optionIdPrefix = "nixos-opt-";
optionIdPrefix = "nixos-opt";
};
}; };
nixDarwinModuleDocs = buildModulesDocs { nixDarwinOptionsDocs = buildOptionsDocs {
modules = [ ../nix-darwin scrubbedPkgsModule dontCheckDefinitions ]; modules = [ ../nix-darwin scrubbedPkgsModule dontCheckDefinitions ];
docBook = { variablelistId = "nix-darwin-options";
id = "nix-darwin-options"; optionIdPrefix = "nix-darwin-opt-";
optionIdPrefix = "nix-darwin-opt";
};
}; };
docs = nmd.buildDocBookDocs { docs = nmd.buildDocBookDocs {
pathName = "home-manager"; pathName = "home-manager";
projectName = "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 = ./.; documentsDirectory = ./.;
documentType = "book"; documentType = "book";
chunkToc = '' chunkToc = ''
@ -81,9 +117,29 @@ in {
inherit nmdSrc; inherit nmdSrc;
options = { options = {
json = hmModulesDocs.json.override { # TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream
path = "share/doc/home-manager/options.json"; # `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; manPages = docs.manPages;

View file

@ -26,7 +26,7 @@
You can use the following options in You can use the following options in
<filename>home-configuration.nix</filename>: <filename>home-configuration.nix</filename>:
</para> </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>
<refsection> <refsection>
<title>See also</title> <title>See also</title>

View file

@ -39,15 +39,15 @@
<xi:include href="faq.xml" /> <xi:include href="faq.xml" />
<appendix xml:id="ch-options"> <appendix xml:id="ch-options">
<title>Configuration Options</title> <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>
<appendix xml:id="ch-nixos-options"> <appendix xml:id="ch-nixos-options">
<title>NixOS Module Options</title> <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>
<appendix xml:id="ch-nix-darwin-options"> <appendix xml:id="ch-nix-darwin-options">
<title>nix-darwin Module Options</title> <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>
<appendix xml:id="ch-tools"> <appendix xml:id="ch-tools">
<title>Tools</title> <title>Tools</title>

View file

@ -105,7 +105,11 @@
packages = forAllSystems (system: packages = forAllSystems (system:
let let
pkgs = nixpkgs.legacyPackages.${system}; 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 ./.; }; hmPkg = pkgs.callPackage ./home-manager { path = toString ./.; };
in { in {
default = hmPkg; default = hmPkg;

View file

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