Merge pull request #171163 from hercules-ci/nixpkgs-config-doc

Add generated `nixpkgs.config` doc to Nixpkgs manual

doc/doc-support/default.nix

@@ -23,6 +23,14 @@ let
       <xsl:import href="${./parameters.xml}"/>
     </xsl:stylesheet>
   '';
+
+  # NB: This file describes the Nixpkgs manual, which happens to use module
+  #     docs infra originally developed for NixOS.
+  optionsDoc = pkgs.nixosOptionsDoc {
+    inherit (pkgs.lib.evalModules { modules = [ ../../pkgs/top-level/config.nix ]; }) options;
+    documentType = "none";
+  };
+
 in pkgs.runCommand "doc-support" {}
 ''
   mkdir result
@@ -30,6 +38,7 @@ in pkgs.runCommand "doc-support" {}
     cd result
     ln -s ${locationsXml} ./function-locations.xml
     ln -s ${functionDocs} ./function-docs
+    ln -s ${optionsDoc.optionsDocBook} ./config-options.docbook.xml
 
     ln -s ${pkgs.docbook5}/xml/rng/docbook/docbook.rng ./docbook.rng
     ln -s ${pkgs.docbook_xsl_ns}/xml/xsl ./xsl

doc/using/configuration.chapter.md

@@ -164,6 +164,14 @@ There are several ways to tweak how Nix handles a package which has been marked
 
     Note that `permittedInsecurePackages` is only checked if `allowInsecurePredicate` is not specified.
 
+### `config` Options Reference
+
+The following attributes can be passed in [`config`](#chap-packageconfig).
+
+```{=docbook}
+<include xmlns="http://www.w3.org/2001/XInclude" href="../doc-support/result/config-options.docbook.xml"/>
+```
+
 ## Modify packages via `packageOverrides` {#sec-modify-via-packageOverrides}
 
 You can define a function called `packageOverrides` in your local `~/.config/nixpkgs/config.nix` to override Nix packages. It must be a function that takes pkgs as an argument and returns a modified set of packages.

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

@@ -20,6 +20,8 @@
 , lib
 , options
 , transformOptions ? lib.id  # function for additional tranformations of the options
+, documentType ? "appendix" # TODO deprecate "appendix" in favor of "none"
+                            #      and/or rename function to moduleOptionDoc for clean slate
 , revision ? "" # Specify revision for the options
 # a set of options the docs we are generating will be merged into, as if by recursiveUpdate.
 # used to split the options doc build into a static part (nixos/modules) and a dynamic part
@@ -161,6 +163,7 @@ in rec {
 
     ${pkgs.python3Minimal}/bin/python ${./sortXML.py} $optionsXML sorted.xml
     ${pkgs.libxslt.bin}/bin/xsltproc \
+      --stringparam documentType '${documentType}' \
       --stringparam revision '${revision}' \
       -o intermediate.xml ${./options-to-docbook.xsl} sorted.xml
     ${pkgs.libxslt.bin}/bin/xsltproc \

nixos/lib/make-options-doc/options-to-docbook.xsl

@@ -12,12 +12,25 @@
   <xsl:output method='xml' encoding="UTF-8" />
 
   <xsl:param name="revision" />
+  <xsl:param name="documentType" />
   <xsl:param name="program" />
 
 
   <xsl:template match="/expr/list">
-    <appendix xml:id="appendix-configuration-options">
-      <title>Configuration Options</title>
+    <xsl:choose>
+      <xsl:when test="$documentType = 'appendix'">
+        <appendix xml:id="appendix-configuration-options">
+          <title>Configuration Options</title>
+          <xsl:call-template name="variable-list"/>
+        </appendix>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="variable-list"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template name="variable-list">
       <variablelist xml:id="configuration-variable-list">
         <xsl:for-each select="attrs">
           <xsl:variable name="id" select="
@@ -102,7 +115,6 @@
         </xsl:for-each>
 
       </variablelist>
-    </appendix>
   </xsl:template>
 
 

pkgs/top-level/config.nix

@@ -20,6 +20,11 @@ let
 
     /* Internal stuff */
 
+    # Hide built-in module system options from docs.
+    _module.args = mkOption {
+      internal = true;
+    };
+
     warnings = mkOption {
       type = types.listOf types.str;
       default = [];