Re: Upstream build system, Sphinx autodoc, Python import path
Hi Thomas, On Thu, Sep 29, 2016 at 11:22:08PM +0200, Thomas Goirand wrote: > On 09/27/2016 10:48 AM, Ben Finney wrote: > > Our wiki page on Library Style Guide advises the Debian packaging > > override the Python import path: > > > > If you need to build the Sphinx documentation (usually from .rst or > > .md files), add: > > > > override_dh_auto_build: > > dh_auto_build > > PYTHONPATH=. sphinx-build -N -bhtml docs/ build/html # HTML > > generator > > PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage > > generator > > If that's what the wiki advise, then it's quite wrong. The target which > should be "overrides" is dh_sphinxdoc. I usually do this: > > override_dh_sphinxdoc: > ifeq (,$(findstring nodocs, $(DEB_BUILD_OPTIONS))) > sphinx-build -b html doc/source \ > $(CURDIR)/debian/foo-doc/usr/share/doc/foo-doc/html > dh_sphinxdoc > endif > > And the same kind of thing for man page. It's IMO nice to have the > nodocs thing if it takes too long to build (probably useless if it's > quick). In such case, overriding the correct debian/rules target is key. I think the modern way to disable docs is using DEB_BUILD_PROFILES=nodoc rather than DEB_BUILD_OPTIONS (because that allows you to actually disable building the foo-doc package, and also allows dropping sphinx build-dep). See [1], [2] for details. Anyway, for non-core Python packages there is usually no reason to care about this, and in that case building the docs in override_dh_auto_build is perfectly fine. And IMO it is semantically more correct to build stuff in build target, rather than install target. [1]: https://wiki.debian.org/BuildProfileSpec#Registered_profile_names [2]: https://wiki.debian.org/DebianBootstrap#Documentation_loops > I don't see why upstream requiring PYTHONPATH=. would be bad... Agreed. -- Dmitry Shachnev signature.asc Description: PGP signature
Re: Upstream build system, Sphinx autodoc, Python import path
Or use the following alternative, which lets the user browse the
documentation offline.
$ cat debian/patches/use-local-python3-doc-for-cross-references
>From f519a948173bfd4e9700a4ebc60bc54bf3455018 Mon Sep 17 00:00:00 2001
From: Florent Rougon
Date: Thu, 8 Oct 2015 13:28:35 -0700
Subject: Use local doc from python3-doc for cross references
Forwarded: not-needed
Last-Update: 2014-10-17
Patch-Name: use-local-python3-doc-for-cross-references
---
doc/conf.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/conf.py b/doc/conf.py
index 728397d..18461c9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -35,7 +35,8 @@ extensions = [
'sphinx.ext.viewcode',
]
-intersphinx_mapping = {'python': ('http://docs.python.org/3', None)}
+intersphinx_mapping = {'python': ('file:///usr/share/doc/python3/html',
+ '/usr/share/doc/python3/html/objects.inv')}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Then put python3-doc in B-D and Suggests or so.
--
Florent
Re: Upstream build system, Sphinx autodoc, Python import path
On Sep 29 2016, Thomas Goirand wrote:
> On 09/27/2016 10:48 AM, Ben Finney wrote:
>> https://wiki.debian.org/Python/LibraryStyleGuide#Sphinx_documentation
>
> I just had a quick look to that page, not only it advises to override
> the wrong dh sequence, but also it gives stupid advices for intersphinx:
>
> "sphinx-build might try to access the Internet to fetch intersphinx
> inventory files; http_proxy set to 127.0.0.1:9 will prevent that."
>
> Instead of attempting circumvention of the effect of using intersphinx,
> it's best to simply *DISABLE* intersphinx in the conf.py of the
> documentation. Setting-up http_proxy / https_proxy to do that, really,
> is the wrong way. Lots of my packages contain intersphinx disabling
> patches.
Even better than disabling intersphinx is to ship the required data in
the package, e.g:
$ cat debian/patches/use-local-intersphinx-inventory.patch
>From 48e6c33f77106b9368e7db430d296ba6c31e47a6 Mon Sep 17 00:00:00 2001
From: Nikolaus Rath
Date: Thu, 8 Oct 2015 12:24:34 -0700
Subject: Use local intersphinx inventory
Forwarded: not-needed
Last-Update: 2011-07-06
Instead of downloading the Python intersphinx directory
at build time, use the cached copy shipped in debian/.
Patch-Name: use-local-intersphinx-inventory.patch
---
rst/conf.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/rst/conf.py b/rst/conf.py
index 2290d..f6425 100644
--- a/rst/conf.py
+++ b/rst/conf.py
@@ -27,7 +27,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
'sphinx_cython' ]
# Link to Python standard library
-intersphinx_mapping = {'python': ('http://docs.python.org/3/', None) }
+intersphinx_mapping = {'python': ('http://docs.python.org/3/',
+ '../debian/python.inv')}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
$ grep intersphinx -C 1 debian/rules
update_intersphinx:
wget http://docs.python.org/3/objects.inv -O debian/python.inv
Best,
-Nikolaus
--
GPG encrypted emails preferred. Key id: 0xD113FCAC3C4E599F
Fingerprint: ED31 791B 2C5C 1613 AF38 8B8A D113 FCAC 3C4E 599F
»Time flies like an arrow, fruit flies like a Banana.«
Re: Upstream build system, Sphinx autodoc, Python import path
On Sep 29, 2016, at 11:30 PM, Thomas Goirand wrote: >I just had a quick look to that page, not only it advises to override >the wrong dh sequence, but also it gives stupid advices for intersphinx: ObDIY: "It's a wiki". :) Cheers, -Barry
Re: Upstream build system, Sphinx autodoc, Python import path
On 09/27/2016 10:48 AM, Ben Finney wrote: > https://wiki.debian.org/Python/LibraryStyleGuide#Sphinx_documentation I just had a quick look to that page, not only it advises to override the wrong dh sequence, but also it gives stupid advices for intersphinx: "sphinx-build might try to access the Internet to fetch intersphinx inventory files; http_proxy set to 127.0.0.1:9 will prevent that." Instead of attempting circumvention of the effect of using intersphinx, it's best to simply *DISABLE* intersphinx in the conf.py of the documentation. Setting-up http_proxy / https_proxy to do that, really, is the wrong way. Lots of my packages contain intersphinx disabling patches. Cheers, Thomas Goirand (zigo)
Re: Upstream build system, Sphinx autodoc, Python import path
On 09/27/2016 10:48 AM, Ben Finney wrote: > Our wiki page on Library Style Guide advises the Debian packaging > override the Python import path: > > If you need to build the Sphinx documentation (usually from .rst or > .md files), add: > > override_dh_auto_build: > dh_auto_build > PYTHONPATH=. sphinx-build -N -bhtml docs/ build/html # HTML > generator > PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage > generator If that's what the wiki advise, then it's quite wrong. The target which should be "overrides" is dh_sphinxdoc. I usually do this: override_dh_sphinxdoc: ifeq (,$(findstring nodocs, $(DEB_BUILD_OPTIONS))) sphinx-build -b html doc/source \ $(CURDIR)/debian/foo-doc/usr/share/doc/foo-doc/html dh_sphinxdoc endif And the same kind of thing for man page. It's IMO nice to have the nodocs thing if it takes too long to build (probably useless if it's quick). In such case, overriding the correct debian/rules target is key. > This is surely not ideal, though. Better would be to not need > ‘PYTHONPATH’ override at all, and just call the build program. PYTHONPATH=. isn't *always* needed, therefore, I don't think it should always be in debian/rules. > What can we advise to upstream so their build system will work correctly > in our build environment *without* that override in every Sphinx-using > package? I don't see why upstream requiring PYTHONPATH=. would be bad... Cheers, Thomas Goirand (zigo)
