From 69648c6cbbecf34c327d73e36b5aed32edfb9ed9 Mon Sep 17 00:00:00 2001 From: Emily Date: Sat, 24 Jun 2023 05:09:22 +0100 Subject: [PATCH] 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). --- doc/manual/default.nix | 261 ++++++--------------------- doc/manual/man-pages.xml | 42 ----- doc/manual/manual.md | 8 + doc/manual/manual.xml | 21 --- doc/manual/overrides.css | 9 - doc/manual/style.css | 291 ------------------------------ modules/documentation/default.nix | 1 - release.nix | 1 - 8 files changed, 66 insertions(+), 568 deletions(-) delete mode 100644 doc/manual/man-pages.xml create mode 100644 doc/manual/manual.md delete mode 100644 doc/manual/manual.xml delete mode 100644 doc/manual/overrides.css delete mode 100644 doc/manual/style.css diff --git a/doc/manual/default.nix b/doc/manual/default.nix index 2ebd51446..2225b5155 100644 --- a/doc/manual/default.nix +++ b/doc/manual/default.nix @@ -40,145 +40,7 @@ let }; }; - sources = lib.sourceFilesBySuffices ./. [".xml"]; - - modulesDoc = builtins.toFile "modules.xml" '' -
- ${(lib.concatMapStrings (path: '' - - '') (lib.catAttrs "value" (config.meta.doc or [])))} -
- ''; - - 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" - '' - - - - - - - ''; - - 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" < - - ]> - - - Allows for cross-referencing olinks between the manpages - and manual. - - - &manualtargets; - - EOF - ''; - in rec { - inherit generatedSources; - # TODO: Use `optionsDoc.optionsJSON` directly once upstream # `nixosOptionsDoc` is more customizable. optionsJSON = runCommand "options.json" @@ -194,10 +56,10 @@ 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"]; } @@ -205,82 +67,75 @@ in rec { # 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 deleted file mode 100644 index 2490f6391..000000000 --- a/doc/manual/man-pages.xml +++ /dev/null @@ -1,42 +0,0 @@ - - Darwin Reference Pages - - DaiderdJordan - Author - - 2016-2019Daiderd Jordan - - - - - - configuration.nix - 5 - Darwin - - - - configuration.nix - Darwin system configuration specification - - - Description - - The file configuration.nix contains the - declarative specification of your Darwin system configuration. The command - darwin-rebuild takes this file and realises the system - configuration specified therein. - - - - Options - - You can use the following options in configuration.nix. - - - - - diff --git a/doc/manual/manual.md b/doc/manual/manual.md new file mode 100644 index 000000000..131df7d25 --- /dev/null +++ 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 deleted file mode 100644 index a334342d6..000000000 --- a/doc/manual/manual.xml +++ /dev/null @@ -1,21 +0,0 @@ - - - Darwin Manual - Version - - - - Preface - Nix modules for darwin. - - - Configuration Options - - - - diff --git a/doc/manual/overrides.css b/doc/manual/overrides.css deleted file mode 100644 index 4c7d4a31b..000000000 --- a/doc/manual/overrides.css +++ /dev/null @@ -1,9 +0,0 @@ -.docbook .xref img[src^=images\/callouts\/], -.screen img, -.programlisting img { - width: 1em; -} - -.calloutlist img { - width: 1.5em; -} diff --git a/doc/manual/style.css b/doc/manual/style.css deleted file mode 100644 index 474dd32e3..000000000 --- a/doc/manual/style.css +++ /dev/null @@ -1,291 +0,0 @@ -/* Copied from http://bakefile.sourceforge.net/, which appears - licensed under the GNU GPL. */ - - -/*************************************************************************** - Basic headers and text: - ***************************************************************************/ - -body -{ - font-family: "Nimbus Sans L", sans-serif; - font-size: 1em; - background: white; - margin: 2em 1em 2em 1em; -} - -h1, h2, h3, h4 -{ - color: #005aa0; -} - -h1 /* title */ -{ - font-size: 200%; -} - -h2 /* chapters, appendices, subtitle */ -{ - font-size: 180%; -} - -div.book -{ - text-align: center; -} - -div.book > div -{ - /* - * based on https://medium.com/@zkareemz/golden-ratio-62b3b6d4282a - * we do 70 characters per line to fit code listings better - * 70 * (font-size / 1.618) - * expression for emacs: - * (* 70 (/ 1 1.618)) - */ - max-width: 43.2em; - text-align: left; - margin: auto; -} - -/* Extra space between chapters, appendices. */ -div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 -{ - margin-top: 1.5em; -} - -div.section > div.titlepage h2 /* sections */ -{ - font-size: 150%; - margin-top: 1.5em; -} - -h3 /* subsections */ -{ - font-size: 125%; -} - -div.simplesect h2 -{ - font-size: 110%; -} - -div.appendix h3 -{ - font-size: 150%; - margin-top: 1.5em; -} - -div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ -{ - margin-top: 1.4em; - font-size: 125%; -} - -div.refsection h3 -{ - font-size: 110%; -} - - -/*************************************************************************** - Examples: - ***************************************************************************/ - -div.example -{ - border: 1px solid #b0b0b0; - padding: 6px 6px; - margin-left: 1.5em; - margin-right: 1.5em; - background: #f4f4f8; - border-radius: 0.4em; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -div.example p.title -{ - margin-top: 0em; -} - -div.example pre -{ - box-shadow: none; -} - - -/*************************************************************************** - Screen dumps: - ***************************************************************************/ - -pre.screen, pre.programlisting -{ - border: 1px solid #b0b0b0; - padding: 3px 3px; - margin-left: 0.5em; - margin-right: 0.5em; - - background: #f4f4f8; - font-family: monospace; - border-radius: 0.4em; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -div.example pre.programlisting -{ - border: 0px; - padding: 0 0; - margin: 0 0 0 0; -} - -/*************************************************************************** - Notes, warnings etc: - ***************************************************************************/ - -.note, .warning -{ - border: 1px solid #b0b0b0; - padding: 3px 3px; - margin-left: 1.5em; - margin-right: 1.5em; - margin-bottom: 1em; - padding: 0.3em 0.3em 0.3em 0.3em; - background: #fffff5; - border-radius: 0.4em; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -div.note, div.warning -{ - font-style: italic; -} - -div.note h3, div.warning h3 -{ - color: red; - font-size: 100%; - padding-right: 0.5em; - display: inline; -} - -div.note p, div.warning p -{ - margin-bottom: 0em; -} - -div.note h3 + p, div.warning h3 + p -{ - display: inline; -} - -div.note h3 -{ - color: blue; - font-size: 100%; -} - -div.navfooter * -{ - font-size: 90%; -} - - -/*************************************************************************** - Links colors and highlighting: - ***************************************************************************/ - -a { text-decoration: none; } -a:hover { text-decoration: underline; } -a:link { color: #0048b3; } -a:visited { color: #002a6a; } - - -/*************************************************************************** - Table of contents: - ***************************************************************************/ - -div.toc -{ - font-size: 90%; -} - -div.toc dl -{ - margin-top: 0em; - margin-bottom: 0em; -} - - -/*************************************************************************** - Special elements: - ***************************************************************************/ - -tt, code -{ - color: #400000; -} - -.term -{ - font-weight: bold; - -} - -div.variablelist dd p, div.glosslist dd p -{ - margin-top: 0em; -} - -div.variablelist dd, div.glosslist dd -{ - margin-left: 1.5em; -} - -div.glosslist dt -{ - font-style: italic; -} - -.varname -{ - color: #400000; -} - -span.command strong -{ - font-weight: normal; - color: #400000; -} - -div.calloutlist table -{ - box-shadow: none; -} - -table -{ - border-collapse: collapse; - box-shadow: 0.4em 0.4em 0.5em #e0e0e0; -} - -table.simplelist -{ - text-align: left; - color: #005aa0; - border: 0; - padding: 5px; - background: #fffff5; - font-weight: normal; - font-style: italic; - box-shadow: none; - margin-bottom: 1em; -} - -div.navheader table, div.navfooter table { - box-shadow: none; -} - -div.affiliation -{ - font-style: italic; -} diff --git a/modules/documentation/default.nix b/modules/documentation/default.nix index 7712a1320..a49d27736 100644 --- a/modules/documentation/default.nix +++ b/modules/documentation/default.nix @@ -73,7 +73,6 @@ let The nix-darwin documentation now requires nixpkgs 23.05 to build. ''; }; - manual = manualHTML; manualHTMLIndex = "${manualHTML}/share/doc/darwin/index.html"; }; diff --git a/release.nix b/release.nix index 56a066352..f5a933550 100644 --- a/release.nix +++ b/release.nix @@ -89,7 +89,6 @@ let }; manualHTML = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manualHTML); - manualEpub = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manualEpub); manpages = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manpages); options = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.optionsJSON);