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> { } }:
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;

View file

@ -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;

View file

@ -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>

View file

@ -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>

View file

@ -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;

View file

@ -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 = {