nixos-render-docs: init from optionsToDocbook.py

this new package shall eventually contain the rendering code necessary
to produce the entirety of the nixos (not nixpkgs) manual, in all of its
various output formats.

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

@@ -155,33 +155,10 @@ in rec {
     OTD_REVISION = revision;
 
     nativeBuildInputs = [
-      (let
-        # python3Minimal can't be overridden with packages on Darwin, due to a missing framework.
-        # Instead of modifying stdenv, we take the easy way out, since most people on Darwin will
-        # just be hacking on the Nixpkgs manual (which also uses make-options-doc).
-        python = if pkgs.stdenv.isDarwin then pkgs.python3 else pkgs.python3Minimal;
-        self = (python.override {
-          inherit self;
-          includeSiteCustomize = true;
-        });
-      in self.withPackages (p:
-        let
-          # TODO add our own small test suite when rendering is split out into a new tool
-          markdown-it-py = p.markdown-it-py.override {
-            disableTests = true;
-          };
-          mdit-py-plugins = p.mdit-py-plugins.override {
-            inherit markdown-it-py;
-            disableTests = true;
-          };
-        in [
-          markdown-it-py
-          mdit-py-plugins
-          p.frozendict
-        ]))
+      pkgs.nixos-render-docs
     ];
   } ''
-    python ${./optionsToDocbook.py} \
+    nixos-render-docs \
       ${lib.optionalString markdownByDefault "--markdown-by-default"} \
       ${optionsJSON}/share/doc/nixos/options.json \
       > options.xml

pkgs/tools/nix/nixos-render-docs/default.nix

@@ -0,0 +1,60 @@
+{ lib
+, stdenv
+, python3
+, python3Minimal
+}:
+
+let
+  # python3Minimal can't be overridden with packages on Darwin, due to a missing framework.
+  # Instead of modifying stdenv, we take the easy way out, since most people on Darwin will
+  # just be hacking on the Nixpkgs manual (which also uses make-options-doc).
+  python = ((if stdenv.isDarwin then python3 else python3Minimal).override {
+    self = python;
+    includeSiteCustomize = true;
+  });
+
+  # TODO add our own small test suite, maybe add tests for these deps to channels?
+  markdown-it-py-no-tests = python.pkgs.markdown-it-py.override {
+    disableTests = true;
+  };
+  mdit-py-plugins-no-tests = python.pkgs.mdit-py-plugins.override {
+    markdown-it-py = markdown-it-py-no-tests;
+    disableTests = true;
+  };
+in
+
+python.pkgs.buildPythonApplication {
+  pname = "nixos-render-docs";
+  version = "0.0";
+  format = "pyproject";
+
+  src = lib.cleanSourceWith {
+    filter = name: type:
+      lib.cleanSourceFilter name type
+      && ! (type == "directory"
+            && builtins.elem
+              (baseNameOf name)
+              [
+                ".pytest_cache"
+                ".mypy_cache"
+                "__pycache__"
+              ]);
+    src = ./src;
+  };
+
+  nativeBuildInputs = [
+    python.pkgs.setuptools
+  ];
+
+  propagatedBuildInputs = [
+    markdown-it-py-no-tests
+    mdit-py-plugins-no-tests
+    python.pkgs.frozendict
+  ];
+
+  meta = with lib; {
+    description = "Renderer for NixOS manual and option docs";
+    license = licenses.mit;
+    maintainers = [ ];
+  };
+}

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/__init__.py

@@ -344,56 +344,57 @@ def print_decl_def(header, locs):
             print(f"""<member><filename{href}>{escape(loc['name'])}</filename></member>""")
     print(f"""</simplelist>""")
 
-markdownByDefault = False
-optOffset = 0
-for arg in sys.argv[1:]:
-    if arg == "--markdown-by-default":
-        optOffset += 1
-        markdownByDefault = True
+def main():
+    markdownByDefault = False
+    optOffset = 0
+    for arg in sys.argv[1:]:
+        if arg == "--markdown-by-default":
+            optOffset += 1
+            markdownByDefault = True
 
-options = convertMD(json.load(open(sys.argv[1 + optOffset], 'r')))
+    options = convertMD(json.load(open(sys.argv[1 + optOffset], 'r')))
 
-keys = list(options.keys())
-keys.sort(key=lambda opt: [ (0 if p.startswith("enable") else 1 if p.startswith("package") else 2, p)
-                            for p in options[opt]['loc'] ])
+    keys = list(options.keys())
+    keys.sort(key=lambda opt: [ (0 if p.startswith("enable") else 1 if p.startswith("package") else 2, p)
+                                for p in options[opt]['loc'] ])
 
-print(f"""<?xml version="1.0" encoding="UTF-8"?>""")
-if OTD_DOCUMENT_TYPE == 'appendix':
-    print("""<appendix xmlns="http://docbook.org/ns/docbook" xml:id="appendix-configuration-options">""")
-    print("""  <title>Configuration Options</title>""")
-print(f"""<variablelist xmlns:xlink="http://www.w3.org/1999/xlink"
-                        xmlns:nixos="tag:nixos.org"
-                        xmlns="http://docbook.org/ns/docbook"
-             xml:id="{OTD_VARIABLE_LIST_ID}">""")
+    print(f"""<?xml version="1.0" encoding="UTF-8"?>""")
+    if OTD_DOCUMENT_TYPE == 'appendix':
+        print("""<appendix xmlns="http://docbook.org/ns/docbook" xml:id="appendix-configuration-options">""")
+        print("""  <title>Configuration Options</title>""")
+    print(f"""<variablelist xmlns:xlink="http://www.w3.org/1999/xlink"
+                            xmlns:nixos="tag:nixos.org"
+                            xmlns="http://docbook.org/ns/docbook"
+                 xml:id="{OTD_VARIABLE_LIST_ID}">""")
 
-for name in keys:
-    opt = options[name]
-    id = OTD_OPTION_ID_PREFIX + name.translate(id_translate_table)
-    print(f"""<varlistentry>""")
-    # NOTE adding extra spaces here introduces spaces into xref link expansions
-    print(f"""<term xlink:href={quoteattr("#" + id)} xml:id={quoteattr(id)}>""", end='')
-    print(f"""<option>{escape(name)}</option>""", end='')
-    print(f"""</term>""")
-    print(f"""<listitem>""")
-    print(opt['description'])
-    if typ := opt.get('type'):
-        print(typ)
-    if default := opt.get('default'):
-        print(default)
-    if example := opt.get('example'):
-        print(example)
-    if related := opt.get('relatedPackages'):
-        print(f"""<para>""")
-        print(f"""  <emphasis>Related packages:</emphasis>""")
-        print(f"""</para>""")
-        print(related)
-    if decl := opt.get('declarations'):
-        print_decl_def("Declared by", decl)
-    if defs := opt.get('definitions'):
-        print_decl_def("Defined by", defs)
-    print(f"""</listitem>""")
-    print(f"""</varlistentry>""")
+    for name in keys:
+        opt = options[name]
+        id = OTD_OPTION_ID_PREFIX + name.translate(id_translate_table)
+        print(f"""<varlistentry>""")
+        # NOTE adding extra spaces here introduces spaces into xref link expansions
+        print(f"""<term xlink:href={quoteattr("#" + id)} xml:id={quoteattr(id)}>""", end='')
+        print(f"""<option>{escape(name)}</option>""", end='')
+        print(f"""</term>""")
+        print(f"""<listitem>""")
+        print(opt['description'])
+        if typ := opt.get('type'):
+            print(typ)
+        if default := opt.get('default'):
+            print(default)
+        if example := opt.get('example'):
+            print(example)
+        if related := opt.get('relatedPackages'):
+            print(f"""<para>""")
+            print(f"""  <emphasis>Related packages:</emphasis>""")
+            print(f"""</para>""")
+            print(related)
+        if decl := opt.get('declarations'):
+            print_decl_def("Declared by", decl)
+        if defs := opt.get('definitions'):
+            print_decl_def("Defined by", defs)
+        print(f"""</listitem>""")
+        print(f"""</varlistentry>""")
 
-print("""</variablelist>""")
-if OTD_DOCUMENT_TYPE == 'appendix':
-    print("""</appendix>""")
+    print("""</variablelist>""")
+    if OTD_DOCUMENT_TYPE == 'appendix':
+        print("""</appendix>""")

pkgs/tools/nix/nixos-render-docs/src/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "nixos-render-docs"
+version = "0.0"
+description = "Renderer for NixOS manual and option docs"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+nixos-render-docs = "nixos_render_docs:main"
+
+[build-system]
+requires = ["setuptools"]

pkgs/top-level/all-packages.nix

@@ -37557,6 +37557,8 @@ with pkgs;
 
   nixos-install-tools = callPackage ../tools/nix/nixos-install-tools { };
 
+  nixos-render-docs = callPackage ../tools/nix/nixos-render-docs { };
+
   nixdoc = callPackage ../tools/nix/nixdoc {};
 
   dnadd = callPackage ../tools/nix/dnadd { };