nixos/lib/make-options-doc/default.nix

   1 /* Generate JSON, XML and DocBook documentation for given NixOS options.
   2
   3    Minimal example:
   4
   5     { pkgs,  }:
   6
   7     let
   8       eval = import (pkgs.path + "/nixos/lib/eval-config.nix") {
   9         baseModules = [
  10           ../module.nix
  11         ];
  12         modules = [];
  13       };
  14     in pkgs.nixosOptionsDoc {
  15       options = eval.options;
  16     }
  17
  18 */
  19 { pkgs
  20 , lib
  21 , options
  22 , transformOptions ? lib.id  # function for additional transformations of the options
  23 , documentType ? "appendix" # TODO deprecate "appendix" in favor of "none"
  24                             #      and/or rename function to moduleOptionDoc for clean slate
  25
  26   # If you include more than one option list into a document, you need to
  27   # provide different ids.
  28 , variablelistId ? "configuration-variable-list"
  29   # String to prefix to the option XML/HTML id attributes.
  30 , optionIdPrefix ? "opt-"
  31 , revision ? "" # Specify revision for the options
  32 # a set of options the docs we are generating will be merged into, as if by recursiveUpdate.
  33 # used to split the options doc build into a static part (nixos/modules) and a dynamic part
  34 # (non-nixos modules imported via configuration.nix, other module sources).
  35 , baseOptionsJSON ? null
  36 # instead of printing warnings for eg options with missing descriptions (which may be lost
  37 # by nix build unless -L is given), emit errors instead and fail the build
  38 , warningsAreErrors ? true
  39 # allow docbook option docs if `true`. only markdown documentation is allowed when set to
  40 # `false`, and a different renderer may be used with different bugs and performance
  41 # characteristics but (hopefully) indistinguishable output.
  42 # deprecated since 23.11.
  43 # TODO remove in a while.
  44 , allowDocBook ? false
  45 # whether lib.mdDoc is required for descriptions to be read as markdown.
  46 # deprecated since 23.11.
  47 # TODO remove in a while.
  48 , markdownByDefault ? true
  49 }:
  50
  51 assert markdownByDefault && ! allowDocBook;
  52
  53 let
  54   rawOpts = lib.optionAttrSetToDocList options;
  55   transformedOpts = map transformOptions rawOpts;
  56   filteredOpts = lib.filter (opt: opt.visible && !opt.internal) transformedOpts;
  57   optionsList = lib.flip map filteredOpts
  58    (opt: opt
  59     // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages opt.name; }
  60    );
  61
  62   # Generate DocBook documentation for a list of packages. This is
  63   # what `relatedPackages` option of `mkOption` from
  64   # ../../../lib/options.nix influences.
  65   #
  66   # Each element of `relatedPackages` can be either
  67   # - a string:  that will be interpreted as an attribute name from `pkgs` and turned into a link
  68   #              to search.nixos.org,
  69   # - a list:    that will be interpreted as an attribute path from `pkgs` and turned into a link
  70   #              to search.nixos.org,
  71   # - an attrset: that can specify `name`, `path`, `comment`
  72   #   (either of `name`, `path` is required, the rest are optional).
  73   #
  74   # NOTE: No checks against `pkgs` are made to ensure that the referenced package actually exists.
  75   # Such checks are not compatible with option docs caching.
  76   genRelatedPackages = packages: optName:
  77     let
  78       unpack = p: if lib.isString p then { name = p; }
  79                   else if lib.isList p then { path = p; }
  80                   else p;
  81       describe = args:
  82         let
  83           title = args.title or null;
  84           name = args.name or (lib.concatStringsSep "." args.path);
  85         in ''
  86           - [${lib.optionalString (title != null) "${title} aka "}`pkgs.${name}`](
  87               https://search.nixos.org/packages?show=${name}&sort=relevance&query=${name}
  88             )${
  89               lib.optionalString (args ? comment) "\n\n  ${args.comment}"
  90             }
  91         '';
  92     in lib.concatMapStrings (p: describe (unpack p)) packages;
  93
  94   optionsNix = builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList);
  95
  96 in rec {
  97   inherit optionsNix;
  98
  99   optionsAsciiDoc = pkgs.runCommand "options.adoc" {
 100     nativeBuildInputs = [ pkgs.nixos-render-docs ];
 101   } ''
 102     nixos-render-docs -j $NIX_BUILD_CORES options asciidoc \
 103       --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
 104       --revision ${lib.escapeShellArg revision} \
 105       ${optionsJSON}/share/doc/nixos/options.json \
 106       $out
 107   '';
 108
 109   optionsCommonMark = pkgs.runCommand "options.md" {
 110     nativeBuildInputs = [ pkgs.nixos-render-docs ];
 111   } ''
 112     nixos-render-docs -j $NIX_BUILD_CORES options commonmark \
 113       --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
 114       --revision ${lib.escapeShellArg revision} \
 115       ${optionsJSON}/share/doc/nixos/options.json \
 116       $out
 117   '';
 118
 119   optionsJSON = pkgs.runCommand "options.json"
 120     { meta.description = "List of NixOS options in JSON format";
 121       nativeBuildInputs = [
 122         pkgs.brotli
 123         pkgs.python3Minimal
 124       ];
 125       options = builtins.toFile "options.json"
 126         (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix));
 127       # merge with an empty set if baseOptionsJSON is null to run markdown
 128       # processing on the input options
 129       baseJSON =
 130         if baseOptionsJSON == null
 131         then builtins.toFile "base.json" "{}"
 132         else baseOptionsJSON;
 133     }
 134     ''
 135       # Export list of options in different format.
 136       dst=$out/share/doc/nixos
 137       mkdir -p $dst
 138
 139       TOUCH_IF_DB=$dst/.used-docbook \
 140       python ${./mergeJSON.py} \
 141         ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
 142         $baseJSON $options \
 143         > $dst/options.json
 144
 145     if grep /nixpkgs/nixos/modules $dst/options.json; then
 146       echo "The manual appears to depend on the location of Nixpkgs, which is bad"
 147       echo "since this prevents sharing via the NixOS channel.  This is typically"
 148       echo "caused by an option default that refers to a relative path (see above"
 149       echo "for hints about the offending path)."
 150       exit 1
 151     fi
 152
 153       brotli -9 < $dst/options.json > $dst/options.json.br
 154
 155       mkdir -p $out/nix-support
 156       echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products
 157       echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products
 158     '';
 159
 160   optionsDocBook = lib.warn "optionsDocBook is deprecated since 23.11 and will be removed in 24.05"
 161     (pkgs.runCommand "options-docbook.xml" {
 162       nativeBuildInputs = [
 163         pkgs.nixos-render-docs
 164       ];
 165     } ''
 166       nixos-render-docs -j $NIX_BUILD_CORES options docbook \
 167         --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
 168         --revision ${lib.escapeShellArg revision} \
 169         --document-type ${lib.escapeShellArg documentType} \
 170         --varlist-id ${lib.escapeShellArg variablelistId} \
 171         --id-prefix ${lib.escapeShellArg optionIdPrefix} \
 172         ${optionsJSON}/share/doc/nixos/options.json \
 173         "$out"
 174     '');
 175 }