Differences between revisions 1 and 2
Revision 1 as of 2020-05-30 21:13:52
Size: 1396
Comment: imported this page from LibraryStyleGuide rev#93. Thanks to BarryWarsaw, FedericoCeratto, ReubenThomas, OndrejNovy, et al.
Revision 2 as of 2020-05-30 21:25:40
Size: 1635
Comment: minor formatting changes; add simplest case example; add more complex case example; add informal TODO section
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== Sphinx documentation == = Sphinx Documentation =
Line 3: Line 3:
If your package has Sphinx documentation, add the {{{sphinxdoc}}} helper like so: If your package has Sphinx documentation, add the {{{sphinxdoc}}} debhelper to the list of existing helpers. The most simple case is as follows:
Line 7: Line 7:
 dh $@ --with python2,python3,sphinxdoc --buildsystem=pybuild  dh $@ --with sphinxdoc
}}}

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

{{{
%:
 dh $@ --with elpa
,python3,sphinxdoc --buildsystem=pybuild
Line 21: Line 28:
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. 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.
Line 25: Line 32:
----
'''TODO:''' Write sections for info and PDF output.

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.