Sphinx Documentation

If your package has Sphinx documentation, add the sphinxdoc debhelper to the list of existing helpers. The most simple case is as follows: 

%:
        dh $@ --with sphinxdoc

More complex cases like the following have also been confirmed to work well: 

%:
        dh $@ --with elpa,python3,sphinxdoc --buildsystem=pybuild

If you need to build the Sphinx documentation (usually from .rst or .md files), add: 

override_dh_auto_build: export http_proxy=127.0.0.1:9
override_dh_auto_build: export https_proxy=127.0.0.1:9
override_dh_auto_build:
        dh_auto_build
        PYTHONPATH=. python3 -m sphinx -N -bhtml docs/ build/html # HTML generator
        PYTHONPATH=. python3 -m sphinx -N -bman docs/ build/man # Manpage generator

Sphinx build might try to access the Internet to fetch intersphinx inventory files; http_proxy (and https_proxy?) set to 127.0.0.1:9 will prevent that.

Another option is to add a patch to use locally installed intersphinx inventory files, but this will be specific to each package. There's no general patch that works for everything, and your package might not even use intersphinx mappings. Debian bug #830186 describes one such approach.

TODO: Write sections for info and PDF output.

-- Rev #1 of this page was imported from The Python Library Style Guide revision #93. Thanks to BarryWarsaw, FedericoCeratto, ?ReubenThomas, ?OndrejNovy, et al, for their work on this documentation.