Re: pybuild sphinxdoc and extensions

[Thomas Goirand <zigo@debian.org>]

On 04/06/2014 03:32 PM, PICCA Frederic-Emmanuel wrote:
> Hello
> 
> I try to find a way to teach my rules files how to generate the documentation using pybuild
> 
> I found the classique
> 
> override_dh_auto_build-indep:
>         dh_auto_build
>         PYTHONPATH=. http_proxy='localhost' sphinx-build -N -bhtml doc/source build/html  # HTML generator
> 
> 
> but is does not work because my package contain binary extensions.
> 
> so I would like to know how to change this snipset to use the {build_dir} for the PYTHONPATH.
> 
> Thanks
> 
> Frederic.
> 
> I propose to add this information in the wiki :)

Hi,

I have usually found the above not the best way to do it. I usually do
it this way:

override_dh_sphinxdoc:
ifeq (,$(findstring nodocs, $(DEB_BUILD_OPTIONS)))
        sphinx-build -b html doc/source \
		$(CURDIR)/debian/$$PKG/usr/share/doc/$$PKG/html
        dh_sphinxdoc -O--buildsystem=python_distutils
endif

So sphinx builds directly in the destination. You then only need to add
a .doc-base file and you're good to go. The advantage is that you can
*not* build the docs if you wish (if you're testing your packaging, and
don't care when doing the tests), and also you wont need to clean
build/html.

As for http_proxy='localhost', it's much better to write
http_proxy='127.0.0.1:9', as there really could be a web proxy running
on localhost, and you don't really want to use it, do you? Also, are you
doing like this to avoid intersphinx? In this case, why don't you just
remove the intersphinx extension from conf.py? That's IMO much cleaner
than just blocking the connection.

I'm not sure about your "binary extensions" thing though...

Cheers,

Thomas Goirand (zigo)