doc/manual: use nixos-render-docs

Now that all the DocBook documentation is gone, we can switch to the new NixOS documentation generator. No meaningful change in HTML output, except that I removed the rather pointless preface and changed the title accordingly. Manual page output is greatly improved; it was kind of broken before. The `sed` hack is pretty gross but I have confirmed that nixpkgs will be happy to accept a PR to make things a little more customizable. This also drops the `manual` alias (deprecated in nixpkgs in 2018 and imported into nix-darwin), and `manualEpub` (because the NixOS documentation generator doesn't support it and also nobody wants this as an ebook).
LnL7 · Jun 24, 2023 · 69648c6 · 69648c6
1 parent d37abf4
commit 69648c6
Show file tree

Hide file tree

Showing 8 changed files with 66 additions and 568 deletions.
diff --git a/doc/manual/default.nix b/doc/manual/default.nix
@@ -40,145 +40,7 @@ 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 or [])))}
-    </section>
-  '';
-
-  generatedSources = runCommand "generated-docbook" {} ''
-    mkdir $out
-    ln -s ${modulesDoc} $out/modules.xml
-    ln -s ${optionsDoc.optionsDocBook} $out/options-db.xml
-    printf "%s" "${version}" > $out/version
-  '';
-
-  copySources =
-    ''
-      cp -prd $sources/* . || true
-      ln -s ${generatedSources} ./generated
-      chmod -R u+w .
-    '';
-
-  toc = builtins.toFile "toc.xml"
-    ''
-      <toc role="chunk-toc">
-        <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-darwin-manual"><?dbhtml filename="index.html"?>
-          <d:tocentry linkend="ch-options"><?dbhtml filename="options.html"?></d:tocentry>
-          <d:tocentry linkend="ch-release-notes"><?dbhtml filename="release-notes.html"?></d:tocentry>
-        </d:tocentry>
-      </toc>
-    '';
-
-  manualXsltprocOptions = toString [
-    "--param section.autolabel 1"
-    "--param section.label.includes.component.label 1"
-    "--stringparam html.stylesheet 'style.css overrides.css highlightjs/mono-blue.css'"
-    "--stringparam html.script './highlightjs/highlight.pack.js ./highlightjs/loader.js'"
-    "--param xref.with.number.and.title 1"
-    "--param toc.section.depth 3"
-    "--stringparam admon.style ''"
-    "--stringparam callout.graphics.extension .svg"
-    "--stringparam current.docid manual"
-    "--param chunk.section.depth 0"
-    "--param chunk.first.sections 1"
-    "--param use.id.as.filename 1"
-    "--stringparam generate.toc 'book toc appendix toc'"
-    "--stringparam chunk.toc ${toc}"
-  ];
-
-  manual-combined = runCommand "darwin-manual-combined"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
-      meta.description = "The NixOS manual as plain docbook XML";
-    }
-    ''
-      ${copySources}
-
-      xmllint --xinclude --output ./manual-combined.xml ./manual.xml
-      xmllint --xinclude --noxincludenode \
-         --output ./man-pages-combined.xml ./man-pages.xml
-
-      # outputs the context of an xmllint error output
-      # LEN lines around the failing line are printed
-      function context {
-        # length of context
-        local LEN=6
-        # lines to print before error line
-        local BEFORE=4
-
-        # xmllint output lines are:
-        # file.xml:1234: there was an error on line 1234
-        while IFS=':' read -r file line rest; do
-          echo
-          if [[ -n "$rest" ]]; then
-            echo "$file:$line:$rest"
-            local FROM=$(($line>$BEFORE ? $line - $BEFORE : 1))
-            # number lines & filter context
-            nl --body-numbering=a "$file" | sed -n "$FROM,+$LEN p"
-          else
-            if [[ -n "$line" ]]; then
-              echo "$file:$line"
-            else
-              echo "$file"
-            fi
-          fi
-        done
-      }
-
-      function lintrng {
-        xmllint --debug --noout --nonet \
-          --relaxng ${docbook5}/xml/rng/docbook/docbook.rng \
-          "$1" \
-          2>&1 | context 1>&2
-          # ^ redirect assumes xmllint doesn’t print to stdout
-      }
-
-      lintrng manual-combined.xml
-      lintrng man-pages-combined.xml
-
-      mkdir $out
-      cp manual-combined.xml $out/
-      cp man-pages-combined.xml $out/
-    '';
-
-  olinkDB = runCommand "manual-olinkdb"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
-    }
-    ''
-      xsltproc \
-        ${manualXsltprocOptions} \
-        --stringparam collect.xref.targets only \
-        --stringparam targets.filename "$out/manual.db" \
-        --nonet \
-        ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \
-        ${manual-combined}/manual-combined.xml
-
-      cat > "$out/olinkdb.xml" <<EOF
-      <?xml version="1.0" encoding="utf-8"?>
-      <!DOCTYPE targetset SYSTEM
-        "file://${docbook_xsl_ns}/xml/xsl/docbook/common/targetdatabase.dtd" [
-        <!ENTITY manualtargets SYSTEM "file://$out/manual.db">
-      ]>
-      <targetset>
-        <targetsetinfo>
-            Allows for cross-referencing olinks between the manpages
-            and manual.
-        </targetsetinfo>
-
-        <document targetdoc="manual">&manualtargets;</document>
-      </targetset>
-      EOF
-    '';
-
 in rec {
-  inherit generatedSources;
-
   # TODO: Use `optionsDoc.optionsJSON` directly once upstream
   # `nixosOptionsDoc` is more customizable.
   optionsJSON = runCommand "options.json"
@@ -194,93 +56,86 @@ in rec {
           "$out/share/doc/darwin"
     '';
 
-  # Generate the NixOS manual.
+  # Generate the nix-darwin manual.
   manualHTML = runCommand "darwin-manual-html"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+    { nativeBuildInputs = [ buildPackages.nixos-render-docs ];
+      styles = lib.sourceFilesBySuffices (pkgs.path + "/doc") [ ".css" ];
       meta.description = "The Darwin manual in HTML format";
       allowedReferences = ["out"];
     }
     ''
       # Generate the HTML manual.
       dst=$out/share/doc/darwin
       mkdir -p $dst
-      xsltproc \
-        ${manualXsltprocOptions} \
-        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
-        --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 ${./style.css} $dst/style.css
-      cp ${./overrides.css} $dst/overrides.css
+      cp $styles/style.css $dst
+      cp $styles/overrides.css $dst
       cp -r ${pkgs.documentation-highlighter} $dst/highlightjs
 
+      substitute ${./manual.md} manual.md \
+        --replace '@DARWIN_VERSION@' "${version}"\
+        --replace \
+          '@DARWIN_OPTIONS_JSON@' \
+          ${optionsJSON}/share/doc/darwin/options.json
+
+      # TODO: --manpage-urls?
+      nixos-render-docs -j $NIX_BUILD_CORES manual html \
+        --manpage-urls ${pkgs.writeText "manpage-urls.json" "{}"} \
+        --revision ${lib.escapeShellArg revision} \
+        --generator "nixos-render-docs ${pkgs.lib.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
-    ''; # */
-
-  # Alias for backward compatibility. TODO(@oxij): remove eventually.
-  manual = manualHTML;
+    '';
 
-  # Index page of the NixOS manual.
+  # Index page of the nix-darwin manual.
   manualHTMLIndex = "${manualHTML}/share/doc/darwin/index.html";
 
-  manualEpub = runCommand "darwin-manual-epub"
-    { inherit sources;
-      buildInputs = [ libxml2.bin libxslt.bin zip ];
-    }
-    ''
-      # Generate the epub manual.
-      dst=$out/share/doc/darwin
-
-      xsltproc \
-        ${manualXsltprocOptions} \
-        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
-        --nonet --xinclude --output $dst/epub/ \
-        ${docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
-        ${manual-combined}/manual-combined.xml
-
-      mkdir -p $dst/epub/OEBPS/images/callouts
-      cp -r ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/epub/OEBPS/images/callouts # */
-      echo "application/epub+zip" > mimetype
-      manual="$dst/darwin-manual.epub"
-      zip -0Xq "$manual" mimetype
-      cd $dst/epub && zip -Xr9D "$manual" *
-
-      rm -rf $dst/epub
+  manualEpub = builtins.throw "The nix-darwin EPUB manual has been removed.";
 
-      mkdir -p $out/nix-support
-      echo "doc-epub manual $manual" >> $out/nix-support/hydra-build-products
-    '';
-
-
-  # Generate the NixOS manpages.
+  # Generate the nix-darwin manpages.
   manpages = runCommand "darwin-manpages"
-    { inherit sources;
-      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+    { nativeBuildInputs = [ buildPackages.nixos-render-docs ];
       allowedReferences = ["out"];
     }
     ''
       # Generate manpages.
-      mkdir -p $out/share/man
-      xsltproc --nonet \
-        --maxdepth 6000 \
-        --param man.output.in.separate.dir 1 \
-        --param man.output.base.dir "'$out/share/man/'" \
-        --param man.endnotes.are.numbered 0 \
-        --param man.break.after.slash 1 \
-        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
-        ${docbook_xsl_ns}/xml/xsl/docbook/manpages/docbook.xsl \
-        ${manual-combined}/man-pages-combined.xml
+      mkdir -p $out/share/man/man5
+      nixos-render-docs -j $NIX_BUILD_CORES options manpage \
+        --revision ${lib.escapeShellArg revision} \
+        ${optionsJSON}/share/doc/darwin/options.json \
+        $out/share/man/man5/configuration.nix.5
+
+      # TODO: get these parameterized in upstream nixos-render-docs
+      sed -i -e '
+        /^\.TH / s|NixOS|Darwin|g
+
+        /^\.SH "NAME"$/ {
+          N
+          s|NixOS|Darwin|g
+        }
+
+        /^\.SH "DESCRIPTION"$/ {
+          N; N
+          s|/etc/nixos/configuration|configuration|g
+          s|NixOS|Darwin|g
+          s|nixos|darwin|g
+        }
+
+        /\.SH "AUTHORS"$/ {
+          N; N
+          s|Eelco Dolstra and the Nixpkgs/NixOS contributors|Daiderd Jordan and the nix-darwin contributors|g
+        }
+      ' $out/share/man/man5/configuration.nix.5
     '';
-
 }
diff --git a/doc/manual/man-pages.xml b/doc/manual/man-pages.xml
diff --git a/doc/manual/manual.md b/doc/manual/manual.md
@@ -0,0 +1,8 @@
+# Darwin Configuration Options {#book-darwin-manual}
+## Version @DARWIN_VERSION@
+
+```{=include=} options
+id-prefix: opt-
+list-id: configuration-variable-list
+source: @DARWIN_OPTIONS_JSON@
+```
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
diff --git a/doc/manual/overrides.css b/doc/manual/overrides.css