From 1ee5fcaf0c8a298f24ada56eadec0a83c382410c Mon Sep 17 00:00:00 2001
From: Martin Weinelt <hexa@darmstadt.ccc.de>
Date: Tue, 23 Aug 2022 15:17:26 +0200
Subject: [PATCH] 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.
---
 .../interpreters/python/hooks/default.nix     |  3 +-
 .../interpreters/python/hooks/sphinx-hook.sh  | 43 ++++++++++++++++---
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/pkgs/development/interpreters/python/hooks/default.nix b/pkgs/development/interpreters/python/hooks/default.nix
index 0f175c90920e..5d605b240ad8 100644
--- a/pkgs/development/interpreters/python/hooks/default.nix
+++ b/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) {};
 }
diff --git a/pkgs/development/interpreters/python/hooks/sphinx-hook.sh b/pkgs/development/interpreters/python/hooks/sphinx-hook.sh
index 92cc9e52ed21..5bbb17e21265 100644
--- a/pkgs/development/interpreters/python/hooks/sphinx-hook.sh
+++ b/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
 }