Merge pull request #212684 from pennae/nixos-render-docs

nixos-render-docs: init, use for some manual rendering to docbook

91 files changed, 69 insertions, 7602 deletions

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 0ddb3fa7fbe9..913058746b35 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -68,12 +68,15 @@ let
 
   sources = lib.sourceFilesBySuffices ./. [".xml"];
 
-  modulesDoc = builtins.toFile "modules.xml" ''
-    <section xmlns:xi="http://www.w3.org/2001/XInclude" id="modules">
-    ${(lib.concatMapStrings (path: ''
-      <xi:include href="${path}" />
-    '') (lib.catAttrs "value" config.meta.doc))}
-    </section>
+  modulesDoc = runCommand "modules.xml" {
+    nativeBuildInputs = [ pkgs.nixos-render-docs ];
+  } ''
+    nixos-render-docs manual docbook \
+      --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
+      "$out" \
+      --section \
+        --section-id modules \
+        --chapters ${lib.concatMapStrings (p: "${p.value} ") config.meta.doc}
   '';
 
   generatedSources = runCommand "generated-docbook" {} ''
diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md
index 7129cf8723e6..33b41fe74d29 100644
--- a/nixos/doc/manual/development/meta-attributes.section.md
+++ b/nixos/doc/manual/development/meta-attributes.section.md
@@ -23,7 +23,7 @@ file.
 
   meta = {
     maintainers = with lib.maintainers; [ ericsagnes ];
-    doc = ./default.xml;
+    doc = ./default.md;
     buildDocsInSandbox = true;
   };
 }
@@ -31,7 +31,9 @@ file.
 
 -   `maintainers` contains a list of the module maintainers.
 
--   `doc` points to a valid DocBook file containing the module
+-   `doc` points to a valid [Nixpkgs-flavored CommonMark](
+      https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
+    ) file containing the module
     documentation. Its contents is automatically added to
     [](#ch-configuration). Changes to a module documentation have to
     be checked to not break building the NixOS manual:
@@ -40,26 +42,6 @@ file.
     $ nix-build nixos/release.nix -A manual.x86_64-linux
     ```
 
-    This file should *not* usually be written by hand. Instead it is preferred
-    to write documentation using CommonMark and converting it to CommonMark
-    using pandoc. The simplest documentation can be converted using just
-
-    ```ShellSession
-    $ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart > doc.xml
-    ```
-
-    More elaborate documentation may wish to add one or more of the pandoc
-    filters used to build the remainder of the manual, for example the GNOME
-    desktop uses
-
-    ```ShellSession
-    $ pandoc gnome.md -t docbook --top-level-division=chapter \
-        --extract-media=media -f markdown+smart \
-        --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \
-        --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
-        > gnome.xml
-    ```
-
 -  `buildDocsInSandbox` indicates whether the option documentation for the
    module can be built in a derivation sandbox. This option is currently only
    honored for modules shipped by nixpkgs. User modules and modules taken from
diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml
index 450a5f670f3a..64234f1cc0d7 100644
--- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml
+++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml
@@ -28,7 +28,7 @@
 
   meta = {
     maintainers = with lib.maintainers; [ ericsagnes ];
-    doc = ./default.xml;
+    doc = ./default.md;
     buildDocsInSandbox = true;
   };
 }
@@ -42,8 +42,10 @@
     </listitem>
     <listitem>
       <para>
-        <literal>doc</literal> points to a valid DocBook file containing
-        the module documentation. Its contents is automatically added to
+        <literal>doc</literal> points to a valid
+        <link xlink:href="https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup">Nixpkgs-flavored
+        CommonMark</link> file containing the module documentation. Its
+        contents is automatically added to
         <xref linkend="ch-configuration" />. Changes to a module
         documentation have to be checked to not break building the NixOS
         manual:
@@ -51,27 +53,6 @@
       <programlisting>
 $ nix-build nixos/release.nix -A manual.x86_64-linux
 </programlisting>
-      <para>
-        This file should <emphasis>not</emphasis> usually be written by
-        hand. Instead it is preferred to write documentation using
-        CommonMark and converting it to CommonMark using pandoc. The
-        simplest documentation can be converted using just
-      </para>
-      <programlisting>
-$ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart &gt; doc.xml
-</programlisting>
-      <para>
-        More elaborate documentation may wish to add one or more of the
-        pandoc filters used to build the remainder of the manual, for
-        example the GNOME desktop uses
-      </para>
-      <programlisting>
-$ pandoc gnome.md -t docbook --top-level-division=chapter \
-    --extract-media=media -f markdown+smart \
-    --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \
-    --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
-    &gt; gnome.xml
-</programlisting>
     </listitem>
     <listitem>
       <para>
diff --git a/nixos/doc/manual/md-to-db.sh b/nixos/doc/manual/md-to-db.sh
index a7421bed532e..4698e94f508b 100755
--- a/nixos/doc/manual/md-to-db.sh
+++ b/nixos/doc/manual/md-to-db.sh
@@ -50,21 +50,3 @@ for mf in ${MD_FILES[*]}; do
 done
 
 popd
-
-# now handle module chapters. we'll need extra checks to ensure that we don't process
-# markdown files we're not interested in, so we'll require an x.nix file for ever x.md
-# that we'll convert to xml.
-pushd "$DIR/../../modules"
-
-mapfile -t MD_FILES < <(find . -type f -regex '.*\.md$')
-
-for mf in ${MD_FILES[*]}; do
-  [ -f "${mf%.md}.nix" ] || continue
-
-  pandoc --top-level-division=chapter "$mf" "${pandoc_flags[@]}" -o "${mf%.md}.xml"
-  sed -i -e '1 i <!-- Do not edit this file directly, edit its companion .md instead\
-     and regenerate this file using nixos/doc/manual/md-to-db.sh -->' \
-    "${mf%.md}.xml"
-done
-
-popd
diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix
index 01db7bcbee9b..271af9ba1801 100644
--- a/nixos/lib/make-options-doc/default.nix
+++ b/nixos/lib/make-options-doc/default.nix
@@ -148,42 +148,19 @@ in rec {
   '';
 
   optionsDocBook = pkgs.runCommand "options-docbook.xml" {
-    MANPAGE_URLS = pkgs.path + "/doc/manpage-urls.json";
-    OTD_DOCUMENT_TYPE = documentType;
-    OTD_VARIABLE_LIST_ID = variablelistId;
-    OTD_OPTION_ID_PREFIX = optionIdPrefix;
-    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
-        ]))
+      pkgs.nixos-render-docs
     ];
   } ''
-    python ${./optionsToDocbook.py} \
+    nixos-render-docs options docbook \
+      --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
+      --revision ${lib.