Merge pull request #136100 from KAction/sphinx-hook

New hook: sphinxHook to build documentation into different formats/outputs

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

@@ -169,4 +169,10 @@ in rec {
       name = "wheel-unpack-hook.sh";
       deps = [ wheel ];
     } ./wheel-unpack-hook.sh) {};
+
+  sphinxHook = callPackage ({ sphinx }:
+    makeSetupHook {
+      name = "python${python.pythonVersion}-sphinx-hook";
+      deps = [ sphinx ];
+    } ./sphinx-hook.sh) {};
 }

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

@@ -0,0 +1,57 @@
+# 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.
+
+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"
+            exit 1
+        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
+                break
+            fi
+        done
+    fi
+
+    if [[ -z "${__sphinxRoot}" ]] ; then
+        echo 2>&1 "Sphinx documentation not found, use 'sphinxRoot' variable"
+        exit 1
+    fi
+    sphinx-build -M html "${__sphinxRoot}" ".sphinx/html" -v
+
+    runHook postBuildSphinx
+}
+
+installSphinxPhase() {
+    local docdir=""
+    runHook preInstallSphinx
+
+    docdir="${doc:-$out}/share/doc/${sphinxOutdir:-$name}"
+    mkdir -p "$docdir"
+
+    cp -r .sphinx/html/html "$docdir/"
+    rm -fr "${docdir}/html/_sources" "${docdir}/html/.buildinfo"
+
+    runHook postInstallSphinx
+}
+
+preBuildPhases+=" buildSphinxPhase"
+postPhases+=" installSphinxPhase"

pkgs/development/python-modules/beautifulsoup4/default.nix

@@ -6,12 +6,14 @@
 , pytestCheckHook
 , pythonOlder
 , soupsieve
+, sphinxHook
 }:
 
 buildPythonPackage rec {
   pname = "beautifulsoup4";
   version = "4.11.1";
   format = "setuptools";
+  outputs = ["out" "doc"];
 
   disabled = pythonOlder "3.6";
 
@@ -29,6 +31,7 @@ buildPythonPackage rec {
   checkInputs = [
     pytestCheckHook
   ];
+  nativeBuildInputs = [ sphinxHook ];
 
   pythonImportsCheck = [
     "bs4"

pkgs/development/python-modules/dropbox/default.nix

@@ -8,6 +8,7 @@
 , mock
 , pytest-mock
 , pytestCheckHook
+, sphinxHook
 }:
 
 buildPythonPackage rec {
@@ -16,6 +17,7 @@ buildPythonPackage rec {
   format = "setuptools";
 
   disabled = pythonOlder "3.7";
+  outputs = ["out" "doc"];
 
   src = fetchFromGitHub {
     owner = "dropbox";
@@ -46,6 +48,7 @@ buildPythonPackage rec {
   pythonImportsCheck = [
     "dropbox"
   ];
+  nativeBuildInputs = [ sphinxHook ];
 
   # Set SCOPED_USER_DROPBOX_TOKEN environment variable to a valid value.
   disabledTests = [

pkgs/top-level/python-packages.nix

@@ -106,6 +106,7 @@ in {
   inherit buildSetupcfg;
 
   inherit (callPackage ../development/interpreters/python/hooks { })
+    sphinxHook
     condaInstallHook
     condaUnpackHook
     eggUnpackHook