diff options
Diffstat (limited to 'nixpkgs/nixos/modules/misc/documentation.nix')
| -rw-r--r-- | nixpkgs/nixos/modules/misc/documentation.nix | 92 |
1 files changed, 45 insertions, 47 deletions
diff --git a/nixpkgs/nixos/modules/misc/documentation.nix b/nixpkgs/nixos/modules/misc/documentation.nix index dfad271bcf14..fb2ed5b023be 100644 --- a/nixpkgs/nixos/modules/misc/documentation.nix +++ b/nixpkgs/nixos/modules/misc/documentation.nix @@ -1,4 +1,4 @@ -{ config, options, lib, pkgs, utils, modules, baseModules, extraModules, modulesPath, ... }: +{ config, options, lib, pkgs, utils, modules, baseModules, extraModules, modulesPath, specialArgs, ... }: with lib; @@ -7,9 +7,6 @@ let cfg = config.documentation; allOpts = options; - /* Modules for which to show options even when not imported. */ - extraDocModules = [ ../virtualisation/qemu-vm.nix ]; - canCacheDocs = m: let f = import m; @@ -23,7 +20,7 @@ let docModules = let - p = partition canCacheDocs (baseModules ++ extraDocModules); + p = partition canCacheDocs (baseModules ++ cfg.nixos.extraModules); in { lazy = p.right; @@ -41,7 +38,7 @@ let modules = [ { _module.check = false; } ] ++ docModules.eager; - specialArgs = { + specialArgs = specialArgs // { pkgs = scrubDerivations "pkgs" pkgs; # allow access to arbitrary options for eager modules, eg for getting # option types from lazy modules @@ -64,7 +61,8 @@ let filter = builtins.filterSource (n: t: - (t == "directory" -> baseNameOf n != "tests") + cleanSourceFilter n t + && (t == "directory" -> baseNameOf n != "tests") && (t == "file" -> hasSuffix ".nix" n) ); in @@ -144,6 +142,12 @@ in { imports = [ + ./man-db.nix + ./mandoc.nix + ./assertions.nix + ./meta.nix + ../config/system-path.nix + ../system/etc/etc.nix (mkRenamedOptionModule [ "programs" "info" "enable" ] [ "documentation" "info" "enable" ]) (mkRenamedOptionModule [ "programs" "man" "enable" ] [ "documentation" "man" "enable" ]) (mkRenamedOptionModule [ "services" "nixosManual" "enable" ] [ "documentation" "nixos" "enable" ]) @@ -156,9 +160,9 @@ in enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to install documentation of packages from - <option>environment.systemPackages</option> into the generated system path. + {option}`environment.systemPackages` into the generated system path. See "Multiple-output packages" chapter in the nixpkgs manual for more info. ''; @@ -168,9 +172,9 @@ in man.enable = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to install manual pages. - This also includes <literal>man</literal> outputs. + This also includes `man` outputs. ''; }; @@ -186,27 +190,20 @@ in man.generateCaches = mkOption { type = types.bool; default = false; - description = '' + description = mdDoc '' Whether to generate the manual page index caches. This allows searching for a page or - keyword using utilities like - <citerefentry> - <refentrytitle>apropos</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry> - and the <literal>-k</literal> option of - <citerefentry> - <refentrytitle>man</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry>. + keyword using utilities like {manpage}`apropos(1)` + and the `-k` option of + {manpage}`man(1)`. ''; }; info.enable = mkOption { type = types.bool; default = true; - description = '' - Whether to install info pages and the <command>info</command> command. + description = lib.mdDoc '' + Whether to install info pages and the {command}`info` command. This also includes "info" outputs. ''; }; @@ -214,8 +211,8 @@ in doc.enable = mkOption { type = types.bool; default = true; - description = '' - Whether to install documentation distributed in packages' <literal>/share/doc</literal>. + description = lib.mdDoc '' + Whether to install documentation distributed in packages' `/share/doc`. Usually plain text and/or HTML. This also includes "doc" outputs. ''; @@ -224,16 +221,14 @@ in dev.enable = mkOption { type = types.bool; default = false; - description = '' + description = mdDoc '' Whether to install documentation targeted at developers. - <itemizedlist> - <listitem><para>This includes man pages targeted at developers if <option>documentation.man.enable</option> is - set (this also includes "devman" outputs).</para></listitem> - <listitem><para>This includes info pages targeted at developers if <option>documentation.info.enable</option> - is set (this also includes "devinfo" outputs).</para></listitem> - <listitem><para>This includes other pages targeted at developers if <option>documentation.doc.enable</option> - is set (this also includes "devdoc" outputs).</para></listitem> - </itemizedlist> + * This includes man pages targeted at developers if {option}`documentation.man.enable` is + set (this also includes "devman" outputs). + * This includes info pages targeted at developers if {option}`documentation.info.enable` + is set (this also includes "devinfo" outputs). + * This includes other pages targeted at developers if {option}`documentation.doc.enable` + is set (this also includes "devdoc" outputs). ''; }; @@ -244,8 +239,7 @@ in 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>documentation.man.enable</option> is + <citerefentry><refentrytitle>configuration.nix</refentrytitle><manvolnum>5</manvolnum></citerefentry> if <option>documentation.man.enable</option> is set.</para></listitem> <listitem><para>This includes the HTML manual and the <command>nixos-help</command> command if <option>documentation.doc.enable</option> is set.</para></listitem> @@ -253,10 +247,18 @@ in ''; }; + nixos.extraModules = mkOption { + type = types.listOf types.raw; + default = []; + description = '' + Modules for which to show options even when not imported. + ''; + }; + nixos.options.splitBuild = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Whether to split the option docs build into a cacheable and an uncacheable part. Splitting the build can substantially decrease the amount of time needed to build the manual, but some user modules may be incompatible with this splitting. @@ -266,7 +268,7 @@ in nixos.options.warningsAreErrors = mkOption { type = types.bool; default = true; - description = '' + description = lib.mdDoc '' Treat warning emitted during the option documentation build (eg for missing option descriptions) as errors. ''; @@ -275,18 +277,18 @@ in nixos.includeAllModules = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Whether the generated NixOS's documentation should include documentation for all the options from all the NixOS modules included in the current - <literal>configuration.nix</literal>. Disabling this will make the manual - generator to ignore options defined outside of <literal>baseModules</literal>. + `configuration.nix`. Disabling this will make the manual + generator to ignore options defined outside of `baseModules`. ''; }; nixos.extraModuleSources = mkOption { type = types.listOf (types.either types.path types.str); default = [ ]; - description = '' + description = lib.mdDoc '' Which extra NixOS module paths the generated NixOS's documentation should strip from options. ''; @@ -344,10 +346,6 @@ in environment.systemPackages = [] ++ optional cfg.man.enable manual.manpages ++ optionals cfg.doc.enable [ manual.manualHTML nixos-help ]; - - services.getty.helpLine = mkIf cfg.doc.enable ( - "\nRun 'nixos-help' for the NixOS manual." - ); }) ]); |