Unverified Commit eac2d22d authored by Silvan Mosberger's avatar Silvan Mosberger Committed by GitHub
Browse files

Merge pull request #299650 from philiptaron/issue-208242/nixos/doc 

Avoid top-level `with ...;` in `nixos/doc/`
parents 57d42cb9 58f791c7

nixos/doc/manual/default.nix

+22 −14
Original line number Diff line number Diff line
@@ -9,12 +9,20 @@ 
, prefix ? ../../..

}:



with pkgs;



let

  inherit (lib) hasPrefix removePrefix;



  lib = pkgs.lib;

  inherit (pkgs) buildPackages runCommand docbook_xsl_ns;



  inherit (pkgs.lib)

    hasPrefix

    removePrefix

    flip

    foldr

    types

    mkOption

    escapeShellArg

    concatMapStringsSep

    sourceFilesBySuffices

    ;



  common = import ./common.nix;
@@ -27,7 +35,7 @@ let 
  # E.g. if some `options` came from modules in ${pkgs.customModules}/nix,

  # you'd need to include `extraSources = [ pkgs.customModules ]`

  prefixesToStrip = map (p: "${toString p}/") ([ prefix ] ++ extraSources);

  stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;

  stripAnyPrefixes = flip (foldr removePrefix) prefixesToStrip;



  optionsDoc = buildPackages.nixosOptionsDoc {

    inherit options revision baseOptionsJSON warningsAreErrors;
@@ -42,8 +50,8 @@ let 
  testOptionsDoc = let

      eval = nixos-lib.evalTest {

        # Avoid evaluating a NixOS config prototype.

        config.node.type = lib.types.deferredModule;

        options._module.args = lib.mkOption { internal = true; };

        config.node.type = types.deferredModule;

        options._module.args = mkOption { internal = true; };

      };

    in buildPackages.nixosOptionsDoc {

      inherit (eval) options;
@@ -76,7 +84,7 @@ let 
    substituteInPlace ./configuration/configuration.md \

      --replace \

          '@MODULE_CHAPTERS@' \

          ${lib.escapeShellArg (lib.concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}

          ${escapeShellArg (concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}

    substituteInPlace ./nixos-options.md \

      --replace \

        '@NIXOS_OPTIONS_JSON@' \
@@ -95,7 +103,7 @@ in rec { 
  # Generate the NixOS manual.

  manualHTML = runCommand "nixos-manual-html"

    { nativeBuildInputs = [ buildPackages.nixos-render-docs ];

      inputs = lib.sourceFilesBySuffices ./. [ ".md" ];

      inputs = sourceFilesBySuffices ./. [ ".md" ];

      meta.description = "The NixOS manual in HTML format";

      allowedReferences = ["out"];

    }
@@ -114,8 +122,8 @@ in rec { 


      nixos-render-docs -j $NIX_BUILD_CORES manual html \

        --manpage-urls ${manpageUrls} \

        --revision ${lib.escapeShellArg revision} \

        --generator "nixos-render-docs ${lib.version}" \

        --revision ${escapeShellArg revision} \

        --generator "nixos-render-docs ${pkgs.lib.version}" \

        --stylesheet style.css \

        --stylesheet highlightjs/mono-blue.css \

        --script ./highlightjs/highlight.pack.js \
@@ -147,7 +155,7 @@ in rec { 
              xml:id="book-nixos-manual">

          <info>

            <title>NixOS Manual</title>

            <subtitle>Version ${lib.version}</subtitle>

            <subtitle>Version ${pkgs.lib.version}</subtitle>

          </info>

          <chapter>

            <title>Temporarily unavailable</title>
@@ -199,7 +207,7 @@ in rec { 
      # Generate manpages.

      mkdir -p $out/share/man/man5

      nixos-render-docs -j $NIX_BUILD_CORES options manpage \

        --revision ${lib.escapeShellArg revision} \

        --revision ${escapeShellArg revision} \

        ${optionsJSON}/${common.outputPath}/options.json \

        $out/share/man/man5/configuration.nix.5

    '';

nixos/modules/misc/documentation.nix

+41 −17
Original line number Diff line number Diff line 
{ config, options, lib, pkgs, utils, modules, baseModules, extraModules, modulesPath, specialArgs, ... }:



with lib;



let

  inherit (lib)

    cleanSourceFilter

    concatMapStringsSep

    evalModules

    filter

    functionArgs

    hasSuffix

    isAttrs

    isDerivation

    isFunction

    isPath

    literalExpression

    mapAttrs

    mkIf

    mkMerge

    mkOption

    mkRemovedOptionModule

    mkRenamedOptionModule

    optional

    optionalAttrs

    optionals

    partition

    removePrefix

    types

    warn

    ;



  cfg = config.documentation;

  allOpts = options;
@@ -13,7 +37,7 @@ let 
      instance = f (mapAttrs (n: _: abort "evaluating ${n} for `meta` failed") (functionArgs f));

    in

      cfg.nixos.options.splitBuild

        && builtins.isPath m

        && isPath m

        && isFunction f

        && instance ? options

        && instance.meta.buildDocsInSandbox or true;
@@ -51,12 +75,12 @@ let 
          (name: value:

            let

              wholeName = "${namePrefix}.${name}";

              guard = lib.warn "Attempt to evaluate package ${wholeName} in option documentation; this is not supported and will eventually be an error. Use `mkPackageOption{,MD}` or `literalExpression` instead.";

              guard = warn "Attempt to evaluate package ${wholeName} in option documentation; this is not supported and will eventually be an error. Use `mkPackageOption{,MD}` or `literalExpression` instead.";

            in if isAttrs value then

              scrubDerivations wholeName value

              // optionalAttrs (isDerivation value) {

                outPath = guard "\${${wholeName}}";

                drvPath = guard drvPath;

                drvPath = guard value.drvPath;

              }

            else value

          )
@@ -176,7 +200,7 @@ in 
      enable = mkOption {

        type = types.bool;

        default = true;

        description = lib.mdDoc ''

        description = ''

          Whether to install documentation of packages from

          {option}`environment.systemPackages` into the generated system path.
@@ -188,7 +212,7 @@ in 
      man.enable = mkOption {

        type = types.bool;

        default = true;

        description = lib.mdDoc ''

        description = ''

          Whether to install manual pages.

          This also includes `man` outputs.

        '';
@@ -197,7 +221,7 @@ in 
      man.generateCaches = mkOption {

        type = types.bool;

        default = false;

        description = mdDoc ''

        description = ''

          Whether to generate the manual page index caches.

          This allows searching for a page or

          keyword using utilities like {manpage}`apropos(1)`
@@ -209,7 +233,7 @@ in 
      info.enable = mkOption {

        type = types.bool;

        default = true;

        description = lib.mdDoc ''

        description = ''

          Whether to install info pages and the {command}`info` command.

          This also includes "info" outputs.

        '';
@@ -218,7 +242,7 @@ in 
      doc.enable = mkOption {

        type = types.bool;

        default = true;

        description = lib.mdDoc ''

        description = ''

          Whether to install documentation distributed in packages' `/share/doc`.

          Usually plain text and/or HTML.

          This also includes "doc" outputs.
@@ -228,7 +252,7 @@ in 
      dev.enable = mkOption {

        type = types.bool;

        default = false;

        description = mdDoc ''

        description = ''

          Whether to install documentation targeted at developers.

          * This includes man pages targeted at developers if {option}`documentation.man.enable` is

            set (this also includes "devman" outputs).
@@ -242,7 +266,7 @@ in 
      nixos.enable = mkOption {

        type = types.bool;

        default = true;

        description = lib.mdDoc ''

        description = ''

          Whether to install NixOS's own documentation.



          - This includes man pages like
@@ -256,7 +280,7 @@ in 
      nixos.extraModules = mkOption {

        type = types.listOf types.raw;

        default = [];

        description = lib.mdDoc ''

        description = ''

          Modules for which to show options even when not imported.

        '';

      };
@@ -264,7 +288,7 @@ in 
      nixos.options.splitBuild = mkOption {

        type = types.bool;

        default = true;

        description = lib.mdDoc ''

        description = ''

          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.
@@ -274,7 +298,7 @@ in 
      nixos.options.warningsAreErrors = mkOption {

        type = types.bool;

        default = true;

        description = lib.mdDoc ''

        description = ''

          Treat warning emitted during the option documentation build (eg for missing option

          descriptions) as errors.

        '';
@@ -283,7 +307,7 @@ in 
      nixos.includeAllModules = mkOption {

        type = types.bool;

        default = false;

        description = lib.mdDoc ''

        description = ''

          Whether the generated NixOS's documentation should include documentation for all

          the options from all the NixOS modules included in the current

          `configuration.nix`. Disabling this will make the manual
@@ -294,7 +318,7 @@ in 
      nixos.extraModuleSources = mkOption {

        type = types.listOf (types.either types.path types.str);

        default = [ ];

        description = lib.mdDoc ''

        description = ''

          Which extra NixOS module paths the generated NixOS's documentation should strip

          from options.

        '';