From 49237015d6ee97e46b2c4aa48190e2f4c9114535 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 27 Jun 2022 17:18:02 +0200 Subject: [PATCH 1/8] nixos/doc: Make nixos-manual-combined fail easy to inspect By writing the unchecked outputs before checking them, they will be written to a store path, which appears in the log, and which sticks around even if the build fails. Eventually it is GCed, but until then, you can open the file. If you run it in a terminal+editor combination like VSCode, the failure location is just one Ctrl+click away. --- nixos/doc/manual/default.nix | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index bcb5d0d02f74..1cd769b6a544 100644 --- a/nixos/doc/manual/default.nix +++ b/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" From 4a8bc4fd079b0ea3adf610d2b5ab6a8ceb10d4ce Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 27 Jun 2022 17:21:34 +0200 Subject: [PATCH 2/8] lib/options: Add hint for debugging infinite recursion in docs --- lib/options.nix | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/options.nix b/lib/options.nix index afae1769afdd..3a1c0e540d7c 100644 --- a/lib/options.nix +++ b/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); From aff2dbbc82c63fa8ad389aad5d78a2fc2461fc36 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 27 Jun 2022 17:27:24 +0200 Subject: [PATCH 3/8] make-options-doc: Make variablelist id configurable I've tried XInclude set-xml-id first, but our tooling did not pick up on it. --- nixos/lib/make-options-doc/default.nix | 5 +++++ nixos/lib/make-options-doc/options-to-docbook.xsl | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix index 282b3e7397c4..6649fc41d41a 100644 --- a/nixos/lib/make-options-doc/default.nix +++ b/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 diff --git a/nixos/lib/make-options-doc/options-to-docbook.xsl b/nixos/lib/make-options-doc/options-to-docbook.xsl index 07d69649523f..978d5e2468a8 100644 --- a/nixos/lib/make-options-doc/options-to-docbook.xsl +++ b/nixos/lib/make-options-doc/options-to-docbook.xsl @@ -14,6 +14,7 @@ + @@ -31,7 +32,8 @@ - + + Date: Mon, 27 Jun 2022 17:30:47 +0200 Subject: [PATCH 5/8] nixos/make-options-doc: Support newline md node This occurs in the ast generated for blockquotes. --- nixos/lib/make-options-doc/mergeJSON.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index 7010a8873d5b..0e64efad7efa 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -65,6 +65,8 @@ def convertMD(options: Dict[str, Any]) -> str: return escape(text) def paragraph(self, text): return text + "\n\n" + def newline(self): + return "\n" def codespan(self, text): return f"{text}" def block_code(self, text, info=None): From e04aa1bcd9050ff705b2cb410f6de9520c763b0c Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 27 Jun 2022 17:32:27 +0200 Subject: [PATCH 6/8] nixos/make-options-doc: Escape inline code and code blocks --- nixos/lib/make-options-doc/mergeJSON.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index 0e64efad7efa..c884a671f53b 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -68,10 +68,10 @@ def convertMD(options: Dict[str, Any]) -> str: def newline(self): return "\n" def codespan(self, text): - return f"{text}" + return f"{escape(text)}" def block_code(self, text, info=None): info = f" language={quoteattr(info)}" if info is not None else "" - return f"\n{text}" + return f"\n{escape(text)}" def link(self, link, text=None, title=None): if link[0:1] == '#': attr = "linkend" From 8bff3fef401ed3ead39fd42bd581590ed863026e Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 27 Jun 2022 17:32:48 +0200 Subject: [PATCH 7/8] nixos/make-options-doc: Support block quotes Our tooling would trip without the inner , despite the docbook docs suggesting that occurs in
and vice versa. --- nixos/lib/make-options-doc/mergeJSON.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index c884a671f53b..5f70d07ce4ad 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -104,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}>{text.rstrip()}" + def block_quote(self, text): + return f"
{text}
" def command(self, text): return f"{escape(text)}" def option(self, text): From 7c81905344bd308c62509f93c87274c50ab54092 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 27 Jun 2022 20:03:34 +0200 Subject: [PATCH 8/8] nixos/make-options-doc: Support Nix-provided declaration locations Feature was introduced in https://github.com/NixOS/nixpkgs/pull/174460, but wasn't supported in `mergeJSON.py` yet. --- nixos/lib/make-options-doc/mergeJSON.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index 5f70d07ce4ad..33e5172270b5 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -198,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():