e65131e69c
This process was automated by [my fork of `nix-doc-munge`]; thanks
to @pennae for writing this tool! It automatically checks that the
resulting documentation doesn't change, although my fork loosens
this a little to ignore some irrelevant whitespace and typographical
differences.
As of this commit there is no DocBook remaining in the options
documentation.
You can play along at home if you want to reproduce this commit:
$ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \
nix shell nixpkgs#coreutils \
-c find . -name '*.nix' \
-exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \
{} +
[my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge
143 lines
4.4 KiB
Nix
143 lines
4.4 KiB
Nix
{ config, lib, pkgs, baseModules, modules, ... }:
|
|
|
|
with lib;
|
|
|
|
let
|
|
cfg = config.documentation;
|
|
|
|
# To reference the regular configuration from inside the docs evaluation further down.
|
|
# While not strictly necessary, this extra binding avoids accidental name capture in
|
|
# the future.
|
|
regularConfig = config;
|
|
|
|
argsModule = {
|
|
config._module.args = regularConfig._module.args // {
|
|
modules = [ ];
|
|
};
|
|
};
|
|
|
|
/* For the purpose of generating docs, evaluate options with each derivation
|
|
in `pkgs` (recursively) replaced by a fake with path "\${pkgs.attribute.path}".
|
|
It isn't perfect, but it seems to cover a vast majority of use cases.
|
|
Caveat: even if the package is reached by a different means,
|
|
the path above will be shown and not e.g. `${config.services.foo.package}`. */
|
|
realManual = import ../../doc/manual {
|
|
inherit pkgs config;
|
|
version = config.system.darwinVersion;
|
|
revision = config.system.darwinRevision;
|
|
nixpkgsRevision = config.system.nixpkgsRevision;
|
|
options =
|
|
let
|
|
scrubbedEval = evalModules {
|
|
modules = baseModules ++ [ argsModule ];
|
|
specialArgs = { pkgs = scrubDerivations "pkgs" pkgs; };
|
|
};
|
|
scrubDerivations = namePrefix: pkgSet: mapAttrs
|
|
(name: value:
|
|
let wholeName = "${namePrefix}.${name}"; in
|
|
if isAttrs value then
|
|
scrubDerivations wholeName value
|
|
// (optionalAttrs (isDerivation value) { outPath = "\${${wholeName}}"; })
|
|
else value
|
|
)
|
|
pkgSet;
|
|
in scrubbedEval.options;
|
|
};
|
|
|
|
# TODO: Remove this when dropping 22.11 support.
|
|
manual = realManual //
|
|
lib.optionalAttrs (lib.versionOlder lib.version "23.05-pre") rec {
|
|
optionsJSON = pkgs.writeTextFile {
|
|
name = "options.json-stub";
|
|
destination = "/share/doc/darwin/options.json";
|
|
text = "{}";
|
|
};
|
|
manpages = pkgs.writeTextFile {
|
|
name = "darwin-manpages-stub";
|
|
destination = "/share/man/man5/configuration.nix.5";
|
|
text = ''
|
|
.TH "CONFIGURATION\&.NIX" "5" "01/01/1980" "Darwin" "Darwin Reference Pages"
|
|
.SH "NAME"
|
|
\fIconfiguration\&.nix\fP \- Darwin system configuration specification
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
The nix\-darwin documentation now requires nixpkgs 23.05 to build.
|
|
'';
|
|
};
|
|
manualHTML = pkgs.writeTextFile {
|
|
name = "darwin-manual-html-stub";
|
|
destination = "/share/doc/darwin/index.html";
|
|
text = ''
|
|
<!DOCTYPE html>
|
|
<title>Darwin Configuration Options</title>
|
|
The nix-darwin documentation now requires nixpkgs 23.05 to build.
|
|
'';
|
|
};
|
|
manual = manualHTML;
|
|
manualHTMLIndex = "${manualHTML}/share/doc/darwin/index.html";
|
|
};
|
|
|
|
helpScript = pkgs.writeScriptBin "darwin-help"
|
|
''
|
|
#! ${pkgs.stdenv.shell} -e
|
|
open ${manual.manualHTMLIndex}
|
|
'';
|
|
in
|
|
|
|
{
|
|
options = {
|
|
documentation.enable = mkOption {
|
|
type = types.bool;
|
|
default = true;
|
|
description = lib.mdDoc ''
|
|
Whether to install documentation of packages from
|
|
{option}`environment.systemPackages` into the generated system path.
|
|
|
|
See "Multiple-output packages" chapter in the nixpkgs manual for more info.
|
|
'';
|
|
# which is at ../../../doc/multiple-output.xml
|
|
};
|
|
|
|
documentation.man.enable = mkOption {
|
|
type = types.bool;
|
|
default = true;
|
|
description = lib.mdDoc ''
|
|
Whether to install manual pages and the {command}`man` command.
|
|
This also includes "man" outputs.
|
|
'';
|
|
};
|
|
|
|
documentation.info.enable = mkOption {
|
|
type = types.bool;
|
|
default = true;
|
|
description = lib.mdDoc ''
|
|
Whether to install info pages and the {command}`info` command.
|
|
This also includes "info" outputs.
|
|
'';
|
|
};
|
|
|
|
documentation.doc.enable = mkOption {
|
|
type = types.bool;
|
|
default = true;
|
|
description = lib.mdDoc ''
|
|
Whether to install documentation distributed in packages' `/share/doc`.
|
|
Usually plain text and/or HTML.
|
|
This also includes "doc" outputs.
|
|
'';
|
|
};
|
|
};
|
|
|
|
config = mkIf cfg.enable {
|
|
|
|
programs.man.enable = cfg.man.enable;
|
|
programs.info.enable = cfg.info.enable;
|
|
|
|
environment.systemPackages = mkMerge [
|
|
(mkIf cfg.man.enable [ manual.manpages ])
|
|
(mkIf cfg.doc.enable [ manual.manualHTML helpScript ])
|
|
];
|
|
|
|
system.build.manual = manual;
|
|
|
|
};
|
|
}
|