doc/python: integrate sphinxHook docs

Improve the documentation by moving it from the hook script into the
Python section in the manual and adding code examples.

doc/languages-frameworks/python.section.md

@@ -744,6 +744,53 @@ with the exception of `other` (see `format` in
   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)
@@ -1273,6 +1320,7 @@ are used in `buildPythonPackage`.
 - `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.

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

@@ -1,16 +1,3 @@
-# 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"