Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

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

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

Show key headers only | View raw

[Multipart message — attachments visible in raw view] - view raw

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

Back to linux.debian.maint.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

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