From 54f4992e80df3b8007dd8235c9f8d6ec77eef16f Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Mon, 20 Feb 2023 18:55:15 +0100
Subject: [PATCH] nixos/manual: render html with nixos-render-doc if
 !allowDocBook

this reproduces the docbook-generated html manual exactly enough to
appease the compare workflows while we still support both toolchains.
it's also a lot faster than the docbook toolchain, rendering the entire
html manual in about two seconds on this machine (while docbook needs
about 20).
---
 nixos/doc/manual/default.nix | 90 ++++++++++++++++++++++++------------
 nixos/doc/manual/manual.md   |  5 +-
 2 files changed, 65 insertions(+), 30 deletions(-)

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 714b3efca20a..2e07edd61c2a 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -135,28 +135,32 @@ let
     }
   '';
 
+  prepareManualFromMD = ''
+    cp -r --no-preserve=all $inputs/* .
+
+    substituteInPlace ./manual.md \
+      --replace '@NIXOS_VERSION@' "${version}"
+    substituteInPlace ./configuration/configuration.md \
+      --replace \
+          '@MODULE_CHAPTERS@' \
+          ${lib.escapeShellArg (lib.concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}
+    substituteInPlace ./nixos-options.md \
+      --replace \
+        '@NIXOS_OPTIONS_JSON@' \
+        ${optionsDoc.optionsJSON}/share/doc/nixos/options.json
+    substituteInPlace ./development/writing-nixos-tests.section.md \
+      --replace \
+        '@NIXOS_TEST_OPTIONS_JSON@' \
+        ${testOptionsDoc.optionsJSON}/share/doc/nixos/options.json
+  '';
+
   manual-combined = runCommand "nixos-manual-combined"
     { inputs = lib.sourceFilesBySuffices ./. [ ".xml" ".md" ];
       nativeBuildInputs = [ pkgs.nixos-render-docs pkgs.libxml2.bin pkgs.libxslt.bin ];
       meta.description = "The NixOS manual as plain docbook XML";
     }
     ''
-      cp -r --no-preserve=all $inputs/* .
-
-      substituteInPlace ./manual.md \
-        --replace '@NIXOS_VERSION@' "${version}"
-      substituteInPlace ./configuration/configuration.md \
-        --replace \
-            '@MODULE_CHAPTERS@' \
-            ${lib.escapeShellArg (lib.concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}
-      substituteInPlace ./nixos-options.md \
-        --replace \
-          '@NIXOS_OPTIONS_JSON@' \
-          ${optionsDoc.optionsJSON}/share/doc/nixos/options.json
-      substituteInPlace ./development/writing-nixos-tests.section.md \
-        --replace \
-          '@NIXOS_TEST_OPTIONS_JSON@' \
-          ${testOptionsDoc.optionsJSON}/share/doc/nixos/options.json
+      ${prepareManualFromMD}
 
       nixos-render-docs -j $NIX_BUILD_CORES manual docbook \
         --manpage-urls ${manpageUrls} \
@@ -193,7 +197,14 @@ in rec {
 
   # Generate the NixOS manual.
   manualHTML = runCommand "nixos-manual-html"
-    { nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+    { nativeBuildInputs =
+        if allowDocBook then [
+          buildPackages.libxml2.bin
+          buildPackages.libxslt.bin
+        ] else [
+          buildPackages.nixos-render-docs
+        ];
+      inputs = lib.optionals (! allowDocBook) (lib.sourceFilesBySuffices ./. [ ".md" ]);
       meta.description = "The NixOS manual in HTML format";
       allowedReferences = ["out"];
     }
@@ -201,23 +212,44 @@ in rec {
       # Generate the HTML manual.
       dst=$out/share/doc/nixos
       mkdir -p $dst
-      xsltproc \
-        ${manualXsltprocOptions} \
-        --stringparam id.warnings "1" \
-        --nonet --output $dst/ \
-        ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \
-        ${manual-combined}/manual-combined.xml \
-        |& tee xsltproc.out
-      grep "^ID recommended on" xsltproc.out &>/dev/null && echo "error: some IDs are missing" && false
-      rm xsltproc.out
-
-      mkdir -p $dst/images/callouts
-      cp ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/
 
       cp ${../../../doc/style.css} $dst/style.css
       cp ${../../../doc/overrides.css} $dst/overrides.css
       cp -r ${pkgs.documentation-highlighter} $dst/highlightjs
 
+      ${if allowDocBook then ''
+          xsltproc \
+            ${manualXsltprocOptions} \
+            --stringparam id.warnings "1" \
+            --nonet --output $dst/ \
+            ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \
+            ${manual-combined}/manual-combined.xml \
+            |& tee xsltproc.out
+          grep "^ID recommended on" xsltproc.out &>/dev/null && echo "error: some IDs are missing" && false
+          rm xsltproc.out
+
+          mkdir -p $dst/images/callouts
+          cp ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/
+        '' else ''
+          ${prepareManualFromMD}
+
+          # TODO generator is set like this because the docbook/md manual compare workflow will
+          # trigger if it's different
+          nixos-render-docs -j $NIX_BUILD_CORES manual html \
+            --manpage-urls ${manpageUrls} \
+            --revision ${lib.escapeShellArg revision} \
+            --generator "DocBook XSL Stylesheets V${docbook_xsl_ns.version}" \
+            --stylesheet style.css \
+            --stylesheet overrides.css \
+            --stylesheet highlightjs/mono-blue.css \
+            --script ./highlightjs/highlight.pack.js \
+            --script ./highlightjs/loader.js \
+            --toc-depth 1 \
+            --chunk-toc-depth 1 \
+            ./manual.md \
+            $dst/index.html
+        ''}
+
       mkdir -p $out/nix-support
       echo "nix-build out $out" >> $out/nix-support/hydra-build-products
       echo "doc manual $dst" >> $out/nix-support/hydra-build-products
diff --git a/nixos/doc/manual/manual.md b/nixos/doc/manual/manual.md
index 1972eaeda872..8cb766eeccf6 100644
--- a/nixos/doc/manual/manual.md
+++ b/nixos/doc/manual/manual.md
@@ -47,7 +47,10 @@ development/development.md
 contributing-to-this-manual.chapter.md
 ```
 
-```{=include=} appendix
+```{=include=} appendix html:into-file=//options.html
 nixos-options.md
+```
+
+```{=include=} appendix html:into-file=//release-notes.html
 release-notes/release-notes.md
 ```