nixos-render-docs: add manual html renderer, use it for the nixos manual

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,31 +197,59 @@ 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"];
     }
     ''
       # 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

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
 ```

nixos/modules/services/web-apps/akkoma.md

@@ -318,8 +318,8 @@ to make packages available in the chroot.
 {option}`services.systemd.akkoma.serviceConfig.BindPaths` and
 {option}`services.systemd.akkoma.serviceConfig.BindReadOnlyPaths` permit access to outside paths
 through bind mounts. Refer to
-[{manpage}`systemd.exec(5)`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#BindPaths=)
-for details.
+[`BindPaths=`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#BindPaths=)
+of {manpage}`systemd.exec(5)` for details.
 
 ### Distributed deployment {#modules-services-akkoma-distributed-deployment}
 

nixos/modules/system/boot/networkd.nix

@@ -1948,7 +1948,7 @@ in
           Extra command-line arguments to pass to systemd-networkd-wait-online.
           These also affect per-interface `systemd-network-wait-online@` services.
 
-          See [{manpage}`systemd-networkd-wait-online.service(8)`](https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html) for all available options.
+          See {manpage}`systemd-networkd-wait-online.service(8)` for all available options.
         '';
         type = with types; listOf str;
         default = [];