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. # Generate the NixOS manual.
manual = runCommand "nixos-manual" manualHTML = runCommand "nixos-manual-html"
{ inherit sources; { inherit sources;
nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ]; nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
meta.description = "The NixOS manual in HTML format"; meta.description = "The NixOS manual in HTML format";
@ -281,6 +281,11 @@ in rec {
echo "doc manual $dst" >> $out/nix-support/hydra-build-products 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" manualEpub = runCommand "nixos-manual-epub"
{ inherit sources; { inherit sources;

View file

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

View file

@ -28,7 +28,7 @@ rec {
modules = configurations ++ modules = configurations ++
[ ../modules/virtualisation/qemu-vm.nix [ ../modules/virtualisation/qemu-vm.nix
../modules/testing/test-instrumentation.nix # !!! should only get added for automated test runs ../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; } { key = "qemu"; system.build.qemu = qemu; }
] ++ optional minimal ../modules/testing/minimal-kernel.nix; ] ++ optional minimal ../modules/testing/minimal-kernel.nix;
extraArgs = { inherit nodes; }; extraArgs = { inherit nodes; };

View file

@ -30,7 +30,7 @@ with lib;
Version=1.0 Version=1.0
Type=Application Type=Application
Name=NixOS Manual 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 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. # Setting vesa, we don't get the nvidia driver, which can't work in arm.
services.xserver.videoDrivers = [ "vesa" ]; services.xserver.videoDrivers = [ "vesa" ];
services.nixosManual.enable = false; documentation.nixos.enable = false;
# Include the firmware for various wireless cards. # Include the firmware for various wireless cards.
networking.enableRalinkFirmware = true; networking.enableRalinkFirmware = true;

View file

@ -1,8 +1,72 @@
{ config, lib, pkgs, ... }: { config, lib, pkgs, baseModules, ... }:
with lib; 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"; 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 = { config = {
# Enable in installer, even if the minimal profile disables it. # Enable in installer, even if the minimal profile disables it.
services.nixosManual.enable = mkForce true; documentation.nixos.enable = mkForce true;
# Show the manual. # Show the manual.
services.nixosManual.showManual = true; services.nixosManual.showManual = true;

View file

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

View file

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

View file

@ -1,91 +1,18 @@
# This module includes the NixOS man-pages in the system environment, # This module optionally starts a browser that shows the NixOS manual
# and optionally starts a browser that shows the NixOS manual on one # on one of the virtual consoles which is useful for the installation
# of the virtual consoles. The latter is useful for the installation
# CD. # CD.
{ config, lib, pkgs, baseModules, ... }: { config, lib, pkgs, ... }:
with lib; with lib;
let let cfg = config.services.nixosManual; in
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
{ {
options = { options = {
services.nixosManual.enable = mkOption { # TODO(@oxij): rename this to `.enable` eventually.
type = types.bool;
default = true;
description = ''
Whether to build the NixOS manual pages.
'';
};
services.nixosManual.showManual = mkOption { services.nixosManual.showManual = mkOption {
type = types.bool; type = types.bool;
default = false; 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 = [] boot.extraTTYs = [ "tty${toString cfg.ttyNumber}" ];
++ 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 = mkIf cfg.showManual ["tty${toString cfg.ttyNumber}"]; systemd.services."nixos-manual" = {
description = "NixOS Manual";
systemd.services = optionalAttrs cfg.showManual wantedBy = [ "multi-user.target" ];
{ "nixos-manual" = serviceConfig = {
{ description = "NixOS Manual"; ExecStart = "${cfg.browser} ${config.system.build.manual.manualHTMLIndex}";
wantedBy = [ "multi-user.target" ]; StandardInput = "tty";
serviceConfig = StandardOutput = "tty";
{ ExecStart = "${cfg.browser} ${entry}"; TTYPath = "/dev/tty${toString cfg.ttyNumber}";
StandardInput = "tty"; TTYReset = true;
StandardOutput = "tty"; TTYVTDisallocate = true;
TTYPath = "/dev/tty${toString cfg.ttyNumber}"; Restart = "always";
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; }; 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)); manualEpub = (buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manualEpub));
manpages = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manpages); manpages = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manpages);
manualGeneratedSources = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.generatedSources); manualGeneratedSources = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.generatedSources);

View file

@ -14,7 +14,7 @@ import ./make-test.nix ({ pkgs, ...} : rec {
{ swapDevices = mkOverride 0 { swapDevices = mkOverride 0
[ { device = "/root/swapfile"; size = 128; } ]; [ { device = "/root/swapfile"; size = 128; } ];
environment.variables.EDITOR = mkOverride 0 "emacs"; 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" ]; systemd.tmpfiles.rules = [ "d /tmp 1777 root root 10d" ];
fileSystems = mkVMOverride { "/tmp2" = fileSystems = mkVMOverride { "/tmp2" =
{ fsType = "tmpfs"; { fsType = "tmpfs";