Merge pull request #179351 from hercules-ci/option-docs-improvements

Option docs improvements

lib/options.nix

@@ -242,6 +242,8 @@ rec {
           in if ss != {} then optionAttrSetToDocList' opt.loc ss else [];
         subOptionsVisible = docOption.visible && opt.visible or null != "shallow";
       in
+        # To find infinite recursion in NixOS option docs:
+        # builtins.trace opt.loc
         [ docOption ] ++ optionals subOptionsVisible subOptions) (collect isOption options);
 
 

nixos/doc/manual/default.nix

@@ -133,12 +133,12 @@ let
           # ^ redirect assumes xmllint doesn’t print to stdout
       }
 
-      lintrng manual-combined.xml
-      lintrng man-pages-combined.xml
-
       mkdir $out
       cp manual-combined.xml $out/
       cp man-pages-combined.xml $out/
+
+      lintrng $out/manual-combined.xml
+      lintrng $out/man-pages-combined.xml
     '';
 
   olinkDB = runCommand "manual-olinkdb"

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

@@ -22,6 +22,10 @@
 , 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
+
+  # If you include more than one option list into a document, you need to
+  # provide different ids.
+, variablelistId ? "configuration-variable-list"
 , 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
@@ -177,6 +181,7 @@ in rec {
     ${pkgs.libxslt.bin}/bin/xsltproc \
       --stringparam documentType '${documentType}' \
       --stringparam revision '${revision}' \
+      --stringparam variablelistId '${variablelistId}' \
       -o intermediate.xml ${./options-to-docbook.xsl} sorted.xml
     ${pkgs.libxslt.bin}/bin/xsltproc \
       -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml

nixos/lib/make-options-doc/mergeJSON.py

@@ -57,19 +57,21 @@ def convertMD(options: Dict[str, Any]) -> str:
             try:
                 return super(Renderer, self)._get_method(name)
             except AttributeError:
-                def not_supported(children, **kwargs):
-                    raise NotImplementedError("md node not supported yet", name, children, **kwargs)
+                def not_supported(*args, **kwargs):
+                    raise NotImplementedError("md node not supported yet", name, args, **kwargs)
                 return not_supported
 
         def text(self, text):
             return escape(text)
         def paragraph(self, text):
             return text + "\n\n"
+        def newline(self):
+            return "<literallayout>\n</literallayout>"
         def codespan(self, text):
-            return f"<literal>{text}</literal>"
+            return f"<literal>{escape(text)}</literal>"
         def block_code(self, text, info=None):
             info = f" language={quoteattr(info)}" if info is not None else ""
-            return f"<programlisting{info}>\n{text}</programlisting>"
+            return f"<programlisting{info}>\n{escape(text)}</programlisting>"
         def link(self, link, text=None, title=None):
             if link[0:1] == '#':
                 attr = "linkend"
@@ -102,6 +104,8 @@ def convertMD(options: Dict[str, Any]) -> str:
             # a single paragraph and the original docbook string is no longer
             # available to restore the trailer.
             return f"<{tag}><para>{text.rstrip()}</para></{tag}>"
+        def block_quote(self, text):
+            return f"<blockquote><para>{text}</para></blockquote>"
         def command(self, text):
             return f"<command>{escape(text)}</command>"
         def option(self, text):
@@ -194,7 +198,7 @@ overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))
 for (k, v) in options.items():
     # The _module options are not declared in nixos/modules
     if v.value['loc'][0] != "_module":
-        v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}', v.value['declarations']))
+        v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}' if isinstance(s, str) else s, v.value['declarations']))
 
 # merge both descriptions
 for (k, v) in overrides.items():

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

@@ -14,6 +14,7 @@
   <xsl:param name="revision" />
   <xsl:param name="documentType" />
   <xsl:param name="program" />
+  <xsl:param name="variablelistId" />
 
 
   <xsl:template match="/expr/list">
@@ -31,7 +32,8 @@
   </xsl:template>
 
   <xsl:template name="variable-list">
-      <variablelist xml:id="configuration-variable-list">
+      <variablelist>
+      <xsl:attribute name="id" namespace="http://www.w3.org/XML/1998/namespace"><xsl:value-of select="$variablelistId"/></xsl:attribute>
         <xsl:for-each select="attrs">
           <xsl:variable name="id" select="
             concat('opt-',