Groups > linux.debian.maint.python > #8913

Re: Upstream build system, Sphinx autodoc, Python import path

Path	csiph.com!feeder.erje.net!2.eu.feeder.erje.net!news2.arglkargh.de!news.mixmin.net!aioe.org!bofh.it!news.nic.it!robomod
From	Thomas Goirand <zigo@debian.org>
Newsgroups	linux.debian.maint.python
Subject	Re: Upstream build system, Sphinx autodoc, Python import path
Date	Thu, 29 Sep 2016 23:30:01 +0200
Message-ID	<smR3X-12A-9@gated-at.bofh.it> (permalink)
References	<slWfn-7h7-15@gated-at.bofh.it>
X-Mailbox-Line	From debian-python-request@lists.debian.org Thu Sep 29 21:22:36 2016
Old-Return-Path	<zigo@debian.org>
X-Amavis-Spam-Status	No, score=-6.9 tagged_above=-10000 required=5.3 tests=[BAYES_00=-2, FOURLA=0.1, LDO_WHITELIST=-5, RCVD_IN_DNSWL_NONE=-0.0001] autolearn=ham autolearn_force=no
X-Policyd-Weight	using cached result; rate: -5
X-Enigmail-Draft-Status	N1110
Organization	Debian
User-Agent	Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Icedove/45.2.0
MIME-Version	1.0
Content-Type	text/plain; charset=utf-8
Content-Transfer-Encoding	quoted-printable
X-Mailing-List	<debian-python@lists.debian.org> archive/latest/14255
List-ID	<debian-python.lists.debian.org>
List-URL	<https://lists.debian.org/debian-python/>
List-Archive	https://lists.debian.org/msgid-search/479e273e-ccf6-17c0-d8cb-a926daa3fb4a@debian.org
Approved	robomod@news.nic.it
Lines	45
Sender	robomod@news.nic.it
X-Original-Date	Thu, 29 Sep 2016 23:22:08 +0200
X-Original-Message-ID	<479e273e-ccf6-17c0-d8cb-a926daa3fb4a@debian.org>
X-Original-References	<85h991lodg.fsf@benfinney.id.au>
Xref	csiph.com linux.debian.maint.python:8913

Show key headers only | View raw

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)

Thread

Upstream build system, Sphinx autodoc, Python import path Ben Finney <ben+debian@benfinney.id.au> - 2016-09-27 10:50 +0200
  Re: Upstream build system, Sphinx autodoc, Python import path Thomas Goirand <zigo@debian.org> - 2016-09-29 23:30 +0200
    Re: Upstream build system, Sphinx autodoc, Python import path Dmitry Shachnev <mitya57@debian.org> - 2016-09-30 08:50 +0200
  Re: Upstream build system, Sphinx autodoc, Python import path Thomas Goirand <zigo@debian.org> - 2016-09-29 23:40 +0200
    Re: Upstream build system, Sphinx autodoc, Python import path Barry Warsaw <barry@debian.org> - 2016-09-30 00:00 +0200
    Re: Upstream build system, Sphinx autodoc, Python import path Nikolaus Rath <Nikolaus@rath.org> - 2016-09-30 05:00 +0200
      Re: Upstream build system, Sphinx autodoc, Python import path Florent Rougon <f.rougon@free.fr> - 2016-09-30 08:20 +0200
        Re: Upstream build system, Sphinx autodoc, Python import path Thomas Goirand <zigo@debian.org> - 2016-09-30 12:20 +0200
        Re: Upstream build system, Sphinx autodoc, Python import path Nikolaus Rath <Nikolaus@rath.org> - 2016-09-30 23:20 +0200

csiph-web