Merge pull request #46193 from oxij/nixos/manual-to-doc

nixos: doc: implement #12542
This commit is contained in:
Samuel Dionne-Riel 2018-09-24 00:09:23 -04:00 committed by GitHub
commit ebf041d4bd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 136 additions and 115 deletions

View file

@ -252,7 +252,7 @@ in rec {
''; # */
# Generate the NixOS manual.
manual = runCommand "nixos-manual"
manualHTML = runCommand "nixos-manual-html"
{ inherit sources;
nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
meta.description = "The NixOS manual in HTML format";
@ -281,6 +281,11 @@ in rec {
echo "doc manual $dst" >> $out/nix-support/hydra-build-products
''; # */
# Alias for backward compatibility. TODO(@oxij): remove eventually.
manual = manualHTML;
# Index page of the NixOS manual.
manualHTMLIndex = "${manualHTML}/share/doc/nixos/index.html";
manualEpub = runCommand "nixos-manual-epub"
{ inherit sources;

View file

@ -34,7 +34,7 @@ $ nix-build -A system</screen>
</varlistentry>
<varlistentry>
<term>
<varname>system.build.manual.manual</varname>
<varname>system.build.manual.manualHTML</varname>
</term>
<listitem>
<para>

View file

@ -28,7 +28,7 @@ rec {
modules = configurations ++
[ ../modules/virtualisation/qemu-vm.nix
../modules/testing/test-instrumentation.nix # !!! should only get added for automated test runs
{ key = "no-manual"; services.nixosManual.enable = false; }
{ key = "no-manual"; documentation.nixos.enable = false; }
{ key = "qemu"; system.build.qemu = qemu; }
] ++ optional minimal ../modules/testing/minimal-kernel.nix;
extraArgs = { inherit nodes; };

View file

@ -30,7 +30,7 @@ with lib;
Version=1.0
Type=Application
Name=NixOS Manual
Exec=firefox ${config.system.build.manual.manual}/share/doc/nixos/index.html
Exec=firefox ${config.system.build.manual.manualHTMLIndex}
Icon=text-html
'';

View file

@ -137,7 +137,7 @@ in
# Setting vesa, we don't get the nvidia driver, which can't work in arm.
services.xserver.videoDrivers = [ "vesa" ];
services.nixosManual.enable = false;
documentation.nixos.enable = false;
# Include the firmware for various wireless cards.
networking.enableRalinkFirmware = true;

View file

@ -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>
'';
};
};
};
@ -99,6 +179,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."
);
})
]);
}

View file

@ -22,7 +22,7 @@ with lib;
config = {
# Enable in installer, even if the minimal profile disables it.
services.nixosManual.enable = mkForce true;
documentation.nixos.enable = mkForce true;
# Show the manual.
services.nixosManual.showManual = true;

View file

@ -12,7 +12,7 @@ with lib;
i18n.supportedLocales = [ (config.i18n.defaultLocale + "/UTF-8") ];
documentation.enable = mkDefault false;
services.nixosManual.enable = mkDefault false;
documentation.nixos.enable = mkDefault false;
sound.enable = mkDefault false;
}

View file

@ -276,6 +276,7 @@ with lib;
(mkRenamedOptionModule [ "programs" "info" "enable" ] [ "documentation" "info" "enable" ])
(mkRenamedOptionModule [ "programs" "man" "enable" ] [ "documentation" "man" "enable" ])
(mkRenamedOptionModule [ "services" "nixosManual" "enable" ] [ "documentation" "nixos" "enable" ])
] ++ (flip map [ "blackboxExporter" "collectdExporter" "fritzboxExporter"
"jsonExporter" "minioExporter" "nginxExporter" "nodeExporter"

View file

@ -1,91 +1,18 @@
# This module includes the NixOS man-pages in the system environment,
# and optionally starts a browser that shows the NixOS manual on one
# of the virtual consoles. The latter is useful for the installation
# This module optionally starts a browser that shows the NixOS manual
# on one of the virtual consoles which is useful for the installation
# CD.
{ config, lib, pkgs, baseModules, ... }:
{ config, lib, pkgs, ... }:
with lib;
let
cfg = config.services.nixosManual;
/* 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;
};
entry = "${manual.manual}/share/doc/nixos/index.html";
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" ${entry}
'';
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
let cfg = config.services.nixosManual; in
{
options = {
services.nixosManual.enable = mkOption {
type = types.bool;
default = true;
description = ''
Whether to build the NixOS manual pages.
'';
};
# TODO(@oxij): rename this to `.enable` eventually.
services.nixosManual.showManual = mkOption {
type = types.bool;
default = false;
@ -114,36 +41,28 @@ in
};
config = mkIf cfg.enable {
config = mkIf cfg.showManual {
system.build.manual = manual;
assertions = [{
assertion = config.documentation.nixos.enable;
message = "Can't enable `service.nixosManual.showManual` without `documentation.nixos.enable`";
}];
environment.systemPackages = []
++ optionals config.services.xserver.enable [ desktopItem pkgs.nixos-icons ]
++ optional config.documentation.man.enable manual.manpages
++ optionals config.documentation.doc.enable [ manual.manual helpScript ];
boot.extraTTYs = [ "tty${toString cfg.ttyNumber}" ];
boot.extraTTYs = mkIf cfg.showManual ["tty${toString cfg.ttyNumber}"];
systemd.services = optionalAttrs cfg.showManual
{ "nixos-manual" =
{ description = "NixOS Manual";
wantedBy = [ "multi-user.target" ];
serviceConfig =
{ ExecStart = "${cfg.browser} ${entry}";
StandardInput = "tty";
StandardOutput = "tty";
TTYPath = "/dev/tty${toString cfg.ttyNumber}";
TTYReset = true;
TTYVTDisallocate = true;
Restart = "always";
};
};
systemd.services."nixos-manual" = {
description = "NixOS Manual";
wantedBy = [ "multi-user.target" ];
serviceConfig = {
ExecStart = "${cfg.browser} ${config.system.build.manual.manualHTMLIndex}";
StandardInput = "tty";
StandardOutput = "tty";
TTYPath = "/dev/tty${toString cfg.ttyNumber}";
TTYReset = true;
TTYVTDisallocate = true;
Restart = "always";
};
services.mingetty.helpLine = "\nRun `nixos-help` "
+ lib.optionalString cfg.showManual "or press <Alt-F${toString cfg.ttyNumber}> "
+ "for the NixOS manual.";
};
};

View file

@ -128,7 +128,8 @@ in rec {
channel = import lib/make-channel.nix { inherit pkgs nixpkgs version versionSuffix; };
manual = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manual);
manualHTML = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manualHTML);
manual = manualHTML; # TODO(@oxij): remove eventually
manualEpub = (buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manualEpub));
manpages = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manpages);
manualGeneratedSources = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.generatedSources);

View file

@ -14,7 +14,7 @@ import ./make-test.nix ({ pkgs, ...} : rec {
{ swapDevices = mkOverride 0
[ { device = "/root/swapfile"; size = 128; } ];
environment.variables.EDITOR = mkOverride 0 "emacs";
services.nixosManual.enable = mkOverride 0 true;
documentation.nixos.enable = mkOverride 0 true;
systemd.tmpfiles.rules = [ "d /tmp 1777 root root 10d" ];
fileSystems = mkVMOverride { "/tmp2" =
{ fsType = "tmpfs";