mirror of
https://github.com/nix-community/home-manager
synced 2024-11-10 07:04:17 +00:00
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:
parent
82c157f255
commit
59b933653a
6 changed files with 99 additions and 32 deletions
|
@ -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;
|
||||
|
|
106
docs/default.nix
106
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;
|
||||
|
|
|
@ -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>
|
||||
|
|
|
@ -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>
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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 = {
|
||||
|
|
Loading…
Reference in a new issue