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.
This commit is contained in:
Martin Weinelt 2022-08-23 15:45:14 +02:00
parent 1ee5fcaf0c
commit 8a26deba06
No known key found for this signature in database
GPG key ID: 87C1E9888F856759
2 changed files with 48 additions and 13 deletions

View file

@ -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.

View file

@ -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"