Merge pull request #208983 from pennae/nixos-manual-md

nixos/manual: convert module chapters to markdown

3 files changed, 59 insertions, 0 deletions

diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md
index 946c08efd0a..7129cf8723e 100644
--- a/nixos/doc/manual/development/meta-attributes.section.md
+++ b/nixos/doc/manual/development/meta-attributes.section.md
@@ -40,6 +40,26 @@ 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 9cc58afa1fd..450a5f670f3 100644
--- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml
+++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml
@@ -51,6 +51,27 @@
       <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 4698e94f508..a7421bed532 100755
--- a/nixos/doc/manual/md-to-db.sh
+++ b/nixos/doc/manual/md-to-db.sh
@@ -50,3 +50,21 @@ 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