python3Packages.sphinxHook: Add support for multiple builders

Removes the up until now unused option to specify a `sphinxOutdir` in
favor of allowing to specify multiple builders, which is for example
useful for generating both documentation and manpages using the hook.

Since the output path cannot be determined from within the package we
automatically generate it and add a diversion for manpages, so they land
in the correct output and path.

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

@@ -6,6 +6,7 @@
 , isPy3k
 , ensureNewerSourcesForZipFilesHook
 , findutils
+, installShellFiles
 }:
 
 let
@@ -190,6 +191,6 @@ in rec {
   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

@@ -11,10 +11,17 @@
 # Sphinx build system can depend on arbitrary amount of python modules, client
 # code is responsible for ensuring that all dependencies are present.
 
-buildSphinxPhase() {
-    local __sphinxRoot="" o
+# shellcheck shell=bash
+echo "Sourcing sphinx-hook"
 
+declare -a __sphinxBuilders
+
+buildSphinxPhase() {
+    echo "Executing buildSphinxPhase"
+
+    local __sphinxRoot="" o
     runHook preBuildSphinx
+
     if [[ -n "${sphinxRoot:-}" ]] ; then  # explicit root
         if ! [[ -f "${sphinxRoot}/conf.py" ]] ; then
             echo 2>&1 "$sphinxRoot/conf.py: no such file"
@@ -35,20 +42,42 @@ buildSphinxPhase() {
         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/*
 
-    cp -r .sphinx/html/html "$docdir/"
-    rm -fr "${docdir}/html/_sources" "${docdir}/html/.buildinfo"
+        else
+            # shellcheck disable=2154
+            docdir="${doc:-$out}/share/doc/${pname}"
+
+            mkdir -p "$docdir"
+
+            cp -r ".sphinx/${__builder}/${__builder}" "$docdir/"
+            rm -fr "${docdir}/${__builder}/_sources" "${docdir}/${__builder}/.buildinfo"
+        fi
+    done
 
     runHook postInstallSphinx
 }