diff options
Diffstat (limited to 'nixos/modules/misc/documentation.nix')
-rw-r--r-- | nixos/modules/misc/documentation.nix | 102 |
1 files changed, 99 insertions, 3 deletions
diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index e6ccda5d7f400..9b2e1235b7481 100644 --- a/nixos/modules/misc/documentation.nix +++ b/nixos/modules/misc/documentation.nix @@ -1,8 +1,72 @@ -{ config, lib, pkgs, ... }: +{ config, lib, pkgs, baseModules, ... }: with lib; -let cfg = config.documentation; in +let + + cfg = config.documentation; + + /* 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}`. */ + manual = import ../../doc/manual rec { + inherit pkgs config; + version = config.system.nixos.release; + revision = "release-${version}"; + options = + let + scrubbedEval = evalModules { + modules = [ { nixpkgs.localSystem = config.nixpkgs.localSystem; } ] ++ baseModules; + args = (config._module.args) // { modules = [ ]; }; + 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; + }; + + helpScript = pkgs.writeScriptBin "nixos-help" + '' + #! ${pkgs.runtimeShell} -e + # Finds first executable browser in a colon-separated list. + # (see how xdg-open defines BROWSER) + browser="$( + IFS=: ; for b in $BROWSER; do + [ -n "$(type -P "$b" || true)" ] && echo "$b" && break + done + )" + if [ -z "$browser" ]; then + browser="$(type -P xdg-open || true)" + if [ -z "$browser" ]; then + browser="$(type -P w3m || true)" + if [ -z "$browser" ]; then + echo "$0: unable to start a web browser; please set \$BROWSER" + exit 1 + fi + fi + fi + exec "$browser" ${manual.manualHTMLIndex} + ''; + + desktopItem = pkgs.makeDesktopItem { + name = "nixos-manual"; + desktopName = "NixOS Manual"; + genericName = "View NixOS documentation in a web browser"; + icon = "nix-snowflake"; + exec = "${helpScript}/bin/nixos-help"; + categories = "System"; + }; + +in { @@ -66,6 +130,22 @@ let cfg = config.documentation; in ''; }; + nixos.enable = mkOption { + type = types.bool; + default = true; + description = '' + Whether to install NixOS's own documentation. + <itemizedlist> + <listitem><para>This includes man pages like + <citerefentry><refentrytitle>configuration.nix</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> if <option>man.enable</option> is + set.</para></listitem> + <listitem><para>This includes the HTML manual and the <command>nixos-help</command> command if + <option>doc.enable</option> is set.</para></listitem> + </itemizedlist> + ''; + }; + }; }; @@ -76,6 +156,7 @@ let cfg = config.documentation; in environment.systemPackages = [ pkgs.man-db ]; environment.pathsToLink = [ "/share/man" ]; environment.extraOutputsToInstall = [ "man" ] ++ optional cfg.dev.enable "devman"; + environment.etc."man.conf".source = "${pkgs.man-db}/etc/man_db.conf"; }) (mkIf cfg.info.enable { @@ -86,7 +167,7 @@ let cfg = config.documentation; in if [ -w $out/share/info ]; then shopt -s nullglob for i in $out/share/info/*.info $out/share/info/*.info.gz; do - ${pkgs.texinfo}/bin/install-info $i $out/share/info/dir + ${pkgs.buildPackages.texinfo}/bin/install-info $i $out/share/info/dir done fi ''; @@ -99,6 +180,21 @@ let cfg = config.documentation; in environment.extraOutputsToInstall = [ "doc" ] ++ optional cfg.dev.enable "devdoc"; }) + (mkIf cfg.nixos.enable { + system.build.manual = manual; + + environment.systemPackages = [] + ++ optional cfg.man.enable manual.manpages + ++ optionals cfg.doc.enable ([ manual.manualHTML helpScript ] + ++ optionals config.services.xserver.enable [ desktopItem pkgs.nixos-icons ]); + + services.mingetty.helpLine = mkIf cfg.doc.enable ( + "\nRun `nixos-help` " + + optionalString config.services.nixosManual.showManual "or press <Alt-F${toString config.services.nixosManual.ttyNumber}> " + + "for the NixOS manual." + ); + }) + ]); } |