Merge pull request #188032 from mweinelt/sphinx-hook-builders

doc/languages-frameworks/python.section.md

···
   unittestFlags = [ "-s" "tests" "-v" ];
 ```
 
+##### Using sphinxHook {#using-sphinxhook}
+
+The `sphinxHook` is a helpful tool to build documentation and manpages
+using the popular Sphinx documentation generator.
+It is setup to automatically find common documentation source paths and
+render them using the default `html` style.
+
+```
+  outputs = [
+    "out"
+    "doc"
+  ];
+
+  nativeBuildInputs = [
+    sphinxHook
+  ];
+```
+
+The hook will automatically build and install the artifact into the
+`doc` output, if it exists. It also provides an automatic diversion
+for the artifacts of the `man` builder into the `man` target.
+
+```
+  outputs = [
+    "out"
+    "doc"
+    "man"
+  ];
+
+  # Use multiple builders
+  sphinxBuilders = [
+    "singlehtml"
+    "man"
+  ];
+```
+
+Overwrite `sphinxRoot` when the hook is unable to find your
+documentation source root.
+
+```
+  # Configure sphinxRoot for uncommon paths
+  sphinxRoot = "weird/docs/path";
+```
+
+The hook is also available to packages outside the python ecosystem by
+referencing it using `python3.pkgs.sphinxHook`.
+
 ### Develop local package {#develop-local-package}
 
 As a Python developer you're likely aware of [development mode](http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode)
···
 - `pytestCheckHook` to run tests with `pytest`. See [example usage](#using-pytestcheckhook).
 - `pythonCatchConflictsHook` to check whether a Python package is not already existing.
 - `pythonImportsCheckHook` to check whether importing the listed modules works.
+- `pythonRelaxDepsHook` will relax Python dependencies restrictions for the package.
+  See [example usage](#using-pythonrelaxdepshook).
 - `pythonRemoveBinBytecode` to remove bytecode from the `/bin` folder.
 - `setuptoolsBuildHook` to build a wheel using `setuptools`.
 - `setuptoolsCheckHook` to run tests with `python setup.py test`.
+- `sphinxHook` to build documentation and manpages using Sphinx.
 - `venvShellHook` to source a Python 3 `venv` at the `venvDir` location. A
   `venv` is created if it does not yet exist. `postVenvCreation` can be used to
   to run commands only after venv is first created.
 - `wheelUnpackHook` to move a wheel to the correct folder so it can be installed
   with the `pipInstallHook`.
-- `pythonRelaxDepsHook` will relax Python dependencies restrictions for the package.
-  See [example usage](#using-pythonrelaxdepshook).
 - `unittestCheckHook` will run tests with `python -m unittest discover`. See [example usage](#using-unittestcheckhook).
 
 ### Development mode {#development-mode}

pkgs/development/interpreters/python/hooks/default.nix

···
 , isPy3k
 , ensureNewerSourcesForZipFilesHook
 , findutils
+, installShellFiles
 }:
 
 let
···
   sphinxHook = callPackage ({ sphinx }:
     makeSetupHook {
       name = "python${python.pythonVersion}-sphinx-hook";
-      deps = [ sphinx ];
+      deps = [ sphinx installShellFiles ];
     } ./sphinx-hook.sh) {};
 }

pkgs/development/interpreters/python/hooks/sphinx-hook.sh

···
-# This hook automatically finds Sphinx documentation, builds it in html format
-# and installs it.
-#
-# This hook knows about several popular locations in which subdirectory
-# documentation may be, but in very unusual cases $sphinxRoot directory can be
-# set explicitly.
-#
-# Name of the directory relative to ${doc:-$out}/share/doc is normally also
-# deduced automatically, but can be overridden with $sphinxOutdir variable.
-#
-# Sphinx build system can depend on arbitrary amount of python modules, client
-# code is responsible for ensuring that all dependencies are present.
+# shellcheck shell=bash
+echo "Sourcing sphinx-hook"
+
+declare -a __sphinxBuilders
 
 buildSphinxPhase() {
-    local __sphinxRoot="" o
+    echo "Executing buildSphinxPhase"
 
+    local __sphinxRoot=""
     runHook preBuildSphinx
+
     if [[ -n "${sphinxRoot:-}" ]] ; then  # explicit root
         if ! [[ -f "${sphinxRoot}/conf.py" ]] ; then
             echo 2>&1 "$sphinxRoot/conf.py: no such file"
···
         fi
         __sphinxRoot=$sphinxRoot
     else
-        for o in doc docs doc/source docs/source ; do
-            if [[ -f "$o/conf.py" ]] ; then
-                echo "Sphinx documentation found in $o"
-                __sphinxRoot=$o
+        for candidate in doc docs doc/source docs/source ; do
+            if [[ -f "$candidate/conf.py" ]] ; then
+                echo "Sphinx documentation found in $candidate"
+                __sphinxRoot=$candidate
                 break
             fi
         done
···
         echo 2>&1 "Sphinx documentation not found, use 'sphinxRoot' variable"
         exit 1
     fi
-    sphinx-build -M html "${__sphinxRoot}" ".sphinx/html" -v
+
+    if [ -n "${sphinxBuilders-}" ]; then
+        eval "__sphinxBuilders=($sphinxBuilders)"
+    else
+        __sphinxBuilders=(html)
+    fi
+
+    for __builder in "${__sphinxBuilders[@]}"; do
+        echo "Executing sphinx-build with ${__builder} builder"
+        sphinx-build -M "${__builder}" "${__sphinxRoot}" ".sphinx/${__builder}" -v
+    done
 
     runHook postBuildSphinx
 }
 
 installSphinxPhase() {
+    echo "Executing installSphinxPhase"
+
     local docdir=""
     runHook preInstallSphinx
 
-    docdir="${doc:-$out}/share/doc/${sphinxOutdir:-$name}"
-    mkdir -p "$docdir"
+    for __builder in "${__sphinxBuilders[@]}"; do
+        # divert output for man builder
+        if [ "$__builder" == "man" ]; then
+            installManPage .sphinx/man/man/*
+
+        else
+            # shellcheck disable=2154
+            docdir="${doc:-$out}/share/doc/${pname}"
 
-    cp -r .sphinx/html/html "$docdir/"
-    rm -fr "${docdir}/html/_sources" "${docdir}/html/.buildinfo"
+            mkdir -p "$docdir"
+
+            cp -r ".sphinx/${__builder}/${__builder}" "$docdir/"
+            rm -fr "${docdir}/${__builder}/_sources" "${docdir}/${__builder}/.buildinfo"
+        fi
+    done
 
     runHook postInstallSphinx
 }
 
-preDistPhases+=" buildSphinxPhase"
-postPhases+=" installSphinxPhase"
+preDistPhases+=" buildSphinxPhase installSphinxPhase"

pkgs/tools/backup/borgbackup/default.nix

···
     setuptools-scm
 
     # docs
-    sphinx
+    sphinxHook
     guzzle_sphinx_theme
 
     # shell completions
     installShellFiles
   ];
+
+  sphinxBuilders = [ "singlehtml" "man" ];
 
   buildInputs = [
     libb2
···
   ];
 
   postInstall = ''
-    make -C docs singlehtml
-    mkdir -p $out/share/doc/borg
-    cp -R docs/_build/singlehtml $out/share/doc/borg/html
-
-    make -C docs man
-    mkdir -p $out/share/man
-    cp -R docs/_build/man $out/share/man/man1
-
     installShellCompletion --cmd borg \
       --bash scripts/shell_completions/bash/borg \
       --fish scripts/shell_completions/fish/borg.fish \