doc: make documentation independent from NixOS

Unfortunately this duplicates some code from NixOS but it does allow much more flexibility and, hopefully, stability in the Home Manager documentation. Fixes #254.
2024-06-18 12:38:30 +02:00 · 2018-05-06 22:14:50 +02:00 · 2018-05-06 22:14:50 +02:00 · 1260349384
commit 1260349384
parent 74f4ed5fd2
6 changed files with 485 additions and 22 deletions
--- a/doc/default.nix
+++ b/doc/default.nix
@ -0,0 +1,329 @@
+{ pkgs, options, config, version, revision, extraSources ? [] }:
+
+with pkgs;
+
+let
+  lib = pkgs.lib;
+
+  # Remove invisible and internal options.
+  optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options);
+
+  # Replace functions by the string <function>
+  substFunction = x:
+    if builtins.isAttrs x then lib.mapAttrs (name: substFunction) x
+    else if builtins.isList x then map substFunction x
+    else if lib.isFunction x then "<function>"
+    else x;
+
+  # Generate DocBook documentation for a list of packages. This is
+  # what `relatedPackages` option of `mkOption` from
+  # ../../../lib/options.nix influences.
+  #
+  # Each element of `relatedPackages` can be either
+  # - a string:  that will be interpreted as an attribute name from `pkgs`,
+  # - a list:    that will be interpreted as an attribute path from `pkgs`,
+  # - an attrset: that can specify `name`, `path`, `package`, `comment`
+  #   (either of `name`, `path` is required, the rest are optional).
+  genRelatedPackages = packages:
+    let
+      unpack = p: if lib.isString p then { name = p; }
+                  else if lib.isList p then { path = p; }
+                  else p;
+      describe = args:
+        let
+          name = args.name or (lib.concatStringsSep "." args.path);
+          path = args.path or [ args.name ];
+          package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}'") pkgs);
+        in "<listitem>"
+        + "<para><literal>pkgs.${name} (${package.meta.name})</literal>"
+        + lib.optionalString (!package.meta.available) " <emphasis>[UNAVAILABLE]</emphasis>"
+        + ": ${package.meta.description or "???"}.</para>"
+        + lib.optionalString (args ? comment) "\n<para>${args.comment}</para>"
+        # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting>
+        + lib.optionalString (package.meta ? longDescription) "\n<programlisting>${package.meta.longDescription}</programlisting>"
+        + "</listitem>";
+    in "<itemizedlist>${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}</itemizedlist>";
+
+  optionsListDesc = lib.flip map optionsListVisible (opt: opt // {
+    # Clean up declaration sites to not refer to the NixOS source tree.
+    declarations = map stripAnyPrefixes opt.declarations;
+  }
+  // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; }
+  // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; }
+  // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; }
+  // lib.optionalAttrs (opt ? relatedPackages) { relatedPackages = genRelatedPackages opt.relatedPackages; });
+
+  # We need to strip references to /nix/store/* from options,
+  # including any `extraSources` if some modules came from elsewhere,
+  # or else the build will fail.
+  #
+  # E.g. if some `options` came from modules in ${pkgs.customModules}/nix,
+  # you'd need to include `extraSources = [ pkgs.customModules ]`
+  prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources);
+  stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip;
+
+  # Custom "less" that pushes up all the things ending in ".enable*"
+  # and ".package*"
+  optionLess = a: b:
+    let
+      ise = lib.hasPrefix "enable";
+      isp = lib.hasPrefix "package";
+      cmp = lib.splitByAndCompare ise lib.compare
+                                 (lib.splitByAndCompare isp lib.compare lib.compare);
+    in lib.compareLists cmp a.loc b.loc < 0;
+
+  # Customly sort option list for the man page.
+  optionsList = lib.sort optionLess optionsListDesc;
+
+  # Convert the list of options into an XML file.
+  optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList);
+
+  optionsDocBook = runCommand "options-db.xml" {} ''
+    optionsXML=${optionsXML}
+    if grep /home--manager/modules $optionsXML; then
+      echo "The manual appears to depend on the location of Home Manager, which is bad"
+      echo "since this prevents sharing via the NixOS channel.  This is typically"
+      echo "caused by an option default that refers to a relative path (see above"
+      echo "for hints about the offending path)."
+      exit 1
+    fi
+    ${buildPackages.libxslt.bin}/bin/xsltproc \
+      --stringparam revision '${revision}' \
+      -o $out ${<nixpkgs/nixos/doc/manual/options-to-docbook.xsl>} $optionsXML
+  '';
+
+  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))}
+    </section>
+  '';
+
+  generatedSources = runCommand "generated-docbook" {} ''
+    mkdir $out
+    ln -s ${modulesDoc} $out/modules.xml
+    ln -s ${optionsDocBook} $out/options-db.xml
+    printf "%s" "${version}" > $out/version
+  '';
+
+  copySources =
+    ''
+      cp -prd $sources/* . # */
+      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-home-manager-manual"><?dbhtml filename="index.html"?>
+          <d:tocentry linkend="ch-options"><?dbhtml filename="options.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 "home-manager-manual-combined"
+    { inherit sources;
+      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+      meta.description = "The Home Manager 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 \
+        ${docbook5_xsl}/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://${docbook5_xsl}/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;
+
+  # The Home Manager options in JSON format.
+  optionsJSON = runCommand "options-json"
+    { meta.description = "List of Home Manager options in JSON format";
+    }
+    ''
+      # Export list of options in different format.
+      dst=$out/share/doc/home-manager
+      mkdir -p $dst
+
+      cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON
+        (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList))))
+      } $dst/options.json
+
+      mkdir -p $out/nix-support
+      echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products
+    ''; # */
+
+  # Generate the Home Manager manual.
+  manual = runCommand "home-manager-manual"
+    { inherit sources;
+      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+      meta.description = "The Home Manager manual in HTML format";
+      allowedReferences = ["out"];
+    }
+    ''
+      # Generate the HTML manual.
+      dst=$out/share/doc/home-manager
+      mkdir -p $dst
+      xsltproc \
+        ${manualXsltprocOptions} \
+        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
+        --nonet --output $dst/ \
+        ${docbook5_xsl}/xml/xsl/docbook/xhtml/chunktoc.xsl \
+        ${manual-combined}/manual-combined.xml
+
+      mkdir -p $dst/images/callouts
+      cp ${docbook5_xsl}/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
+
+      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
+    ''; # */
+
+
+  manualEpub = runCommand "home-manager-manual-epub"
+    { inherit sources;
+      buildInputs = [ libxml2.bin libxslt.bin zip ];
+    }
+    ''
+      # Generate the epub manual.
+      dst=$out/share/doc/home-manager
+
+      xsltproc \
+        ${manualXsltprocOptions} \
+        --stringparam target.database.document "${olinkDB}/olinkdb.xml" \
+        --nonet --xinclude --output $dst/epub/ \
+        ${docbook5_xsl}/xml/xsl/docbook/epub/docbook.xsl \
+        ${manual-combined}/manual-combined.xml
+
+      mkdir -p $dst/epub/OEBPS/images/callouts
+      cp -r ${docbook5_xsl}/xml/xsl/docbook/images/callouts/*.svg $dst/epub/OEBPS/images/callouts # */
+      echo "application/epub+zip" > mimetype
+      manual="$dst/home-manager-manual.epub"
+      zip -0Xq "$manual" mimetype
+      cd $dst/epub && zip -Xr9D "$manual" *
+
+      rm -rf $dst/epub
+
+      mkdir -p $out/nix-support
+      echo "doc-epub manual $manual" >> $out/nix-support/hydra-build-products
+    '';
+
+
+  # Generate the Home Manager manpages.
+  manpages = runCommand "home-manager-manpages"
+    { inherit sources;
+      nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+      allowedReferences = ["out"];
+    }
+    ''
+      # Generate manpages.
+      mkdir -p $out/share/man
+      xsltproc --nonet \
+        --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" \
+        ${docbook5_xsl}/xml/xsl/docbook/manpages/docbook.xsl \
+        ${manual-combined}/man-pages-combined.xml
+    '';
+
+}
--- a/doc/man-configuration.xml
+++ b/doc/man-configuration.xml
@ -0,0 +1,34 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refmeta>
+  <refentrytitle><filename>home-configuration.nix</filename></refentrytitle>
+  <manvolnum>5</manvolnum>
+  <refmiscinfo class="source">Home Manager</refmiscinfo>
+<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+ </refmeta>
+
+ <refnamediv>
+  <refname><filename>home-configuration.nix</filename></refname>
+  <refpurpose>Home Manager configuration specification</refpurpose>
+ </refnamediv>
+
+ <refsection>
+  <title>Description</title>
+  <para>
+   The file <filename>~/.config/nixpkgs/home.nix</filename> contains
+   the declarative specification of your Home Manager configuration.
+   The command <command>home-manager</command> takes this file and
+   realises the user environment configuration specified therein.
+  </para>
+ </refsection>
+
+ <refsection>
+  <title>Options</title>
+  <para>
+   You can use the following options in
+   <filename>home-configuration.nix</filename>:
+  </para>
+  <xi:include href="./generated/options-db.xml" xpointer="configuration-variable-list" />
+ </refsection>
+</refentry>
--- a/doc/man-home-manager.xml
+++ b/doc/man-home-manager.xml
@ -0,0 +1,62 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refmeta>
+  <refentrytitle><command>home-manager</command></refentrytitle>
+  <manvolnum>8</manvolnum>
+  <refmiscinfo class="source">Home Manager</refmiscinfo>
+<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+ </refmeta>
+
+ <refnamediv>
+  <refname><command>home-manager</command></refname>
+  <refpurpose>reconfigure a user environment</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>home-manager</command>
+    <group choice='req'>
+     <arg choice='plain'><option>help</option></arg>
+     <arg choice='plain'><option>build</option></arg>
+     <arg choice='plain'><option>switch</option></arg>
+     <arg choice='plain'><option>generations</option></arg>
+     <arg choice='plain'><option>remove-generations</option></arg>
+     <arg choice='plain'><option>packages</option></arg>
+     <arg choice='plain'><option>news</option></arg>
+    </group>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+  <title>Description</title>
+  <para>
+   This command updates the user environment so that it corresponds to the configuration
+   specified in <filename>~/.config/nixpkgs/home.nix</filename>.
+  </para>
+ </refsection>
+
+ <refsection>
+  <title>Files</title>
+  <variablelist>
+   <varlistentry>
+    <term><filename>~/.local/share/home-manager/news-read-ids</filename></term>
+    <listitem>
+     <para>
+      Identifiers of news items that have been shown. Can be deleted
+      to reset the read news indicator.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsection>
+
+ <refsection>
+  <title>Bugs</title>
+  <para>
+   Please report any bugs on the <link
+   xlink:href="https://github.com/rycee/home-manager/issues">project
+   issue tracker</link>.
+  </para>
+ </refsection>
+</refentry>
--- a/doc/man-pages.xml
+++ b/doc/man-pages.xml
@ -0,0 +1,16 @@
+<reference xmlns="http://docbook.org/ns/docbook"
+           xmlns:xlink="http://www.w3.org/1999/xlink"
+           xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>Home Manager Reference Pages</title>
+ <info>
+  <author>
+   <personname>Home Manager contributors</personname>
+   <contrib>Author</contrib>
+  </author>
+  <copyright>
+   <year>2017-2018</year><holder>Home Manager contributors</holder>
+  </copyright>
+ </info>
+ <xi:include href="man-configuration.xml" />
+ <xi:include href="man-home-manager.xml" />
+</reference>
--- a/doc/manual.xml
+++ b/doc/manual.xml
@ -0,0 +1,40 @@
+<book xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="book-nixos-manual">
+ <info>
+  <title>Home Manager Manual</title>
+ </info>
+ <preface>
+  <title>Preface</title>
+  <para>
+   This manual will eventually describes how to install, use and
+   extend Home Manager.
+  </para>
+  <para>
+   If you encounter problems, please report them on the
+   <literal
+    xlink:href="https://groups.google.com/forum/#!forum/nix-devel">nix-devel</literal>
+   mailing list or on the <link
+    xlink:href="irc://irc.freenode.net/#nixos">
+   <literal>#nixos</literal> channel on Freenode</link>. Bugs should be
+   reported in
+   <link
+    xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’
+   GitHub issue tracker</link>.
+  </para>
+  <note>
+   <para>
+    Commands prefixed with <literal>#</literal> have to be run as root, either
+    requiring to login as root user or temporarily switching to it using
+    <literal>sudo</literal> for example.
+   </para>
+  </note>
+ </preface>
+ <appendix xml:id="ch-options">
+  <title>Configuration Options</title>
+  <xi:include href="./generated/options-db.xml"
+                xpointer="configuration-variable-list" />
+ </appendix>
+</book>
--- a/modules/manual.nix
+++ b/modules/manual.nix
@ -9,14 +9,14 @@ let
    It isn't perfect, but it seems to cover a vast majority of use cases.
    Caveat: even if the package is reached by a different means,
    the path above will be shown and not e.g. `${config.services.foo.package}`. */
-  nixosManual = import <nixpkgs/nixos/doc/manual> {
+  homeManagerManual = import <home-manager/doc> {
    inherit pkgs config;
    version = "0.1";
    revision = "release-0.1";
    options =
      let
        scrubbedEval = evalModules {
-          modules = [ { nixpkgs.system = pkgs.stdenv.system; } ] ++ baseModules;
+          modules = [ { nixpkgs.localSystem = config.nixpkgs.localSystem; } ] ++ baseModules;
          args = (config._module.args) // { modules = [ ]; };
          specialArgs = { pkgs = scrubDerivations "pkgs" pkgs; };
        };
@ -32,14 +32,6 @@ let
      in scrubbedEval.options;
  };

-  homeEnvironmentManPages = pkgs.runCommand "home-environment-manpages" {
-      allowedReferences = [ "out" ];
-    } ''
-      install -v -D -m444 \
-        ${nixosManual.manpages}/share/man/man5/configuration.nix.5 \
-        $out/share/man/man5/home-configuration.nix.5
-    '';
-
 in

 {
@ -60,22 +52,12 @@ in
  };

  config = mkIf config.manual.manpages.enable {
-    home.packages = [ homeEnvironmentManPages ];
+    home.packages = [ homeManagerManual.manpages ];
  };

  # To fix error during manpage build.
  meta = {
    maintainers = [ maintainers.rycee ];
-    doc = builtins.toFile "nothingness" ''
-      <chapter xmlns="http://docbook.org/ns/docbook"
-               xmlns:xlink="http://www.w3.org/1999/xlink"
-               xmlns:xi="http://www.w3.org/2001/XInclude"
-               version="5.0"
-               xml:id="sec-nothing">
-        <title>this is just to make the docs compile</title>
-        <para xml:id="sec-grsecurity"></para>
-        <para xml:id="sec-emacs-docbook-xml"></para>
-      </chapter>
-    '';
+    doc = builtins.toFile "nothingness" "";
  };
 }