= 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.
[[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=830186|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 [[https://wiki.debian.org/Python/LibraryStyleGuide?action=recall&rev=93|revision #93.]]  Thanks to BarryWarsaw, FedericoCeratto, ReubenThomas, OndrejNovy, et al, for their work on this documentation.