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

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

4 files changed, 18 insertions, 70 deletions

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 0ddb3fa7fbe..913058746b3 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 7129cf8723e..33b41fe74d2 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 450a5f670f3..64234f1cc0d 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 a7421bed532..4698e94f508 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