Re: providing sphinx3-* binaries

[Thomas Goirand <zigo@debian.org>]

Hi Antoine,

Thanks for your post.

On 09/27/2017 12:29 AM, Antoine Beaupré wrote:
>  6. there are currently packages depending on *both* python-sphinx and
>     python3-sphinx. for me, that makes no sense at all: there is a
>     single set of documentation files built in a package, and it must be
>     on either one of those packages, but not both. if the software
>     supports building with python3, then it should depend on
>     python3-sphinx, if not, it should depend on python-sphinx. by
>     switching to sphinx{,3} binary packages, this would make that
>     distinction clearer as well.

It does make sense if the package is a sphinx extension, and it has
tests that you may want to run in both Python 2 and 3 cases. I do have a
few of these cases (even though I'm planning on switching to Python3
support only in the short term).

On 09/28/2017 02:27 PM, Antoine Beaupré wrote:
> A simple --with=sphinxdoc should be sufficient to build sphinx docs.
> We shouldn't expect upstream to do that step in setup.py, as it is
> rarely hooked into the main build.

I don't agree with this. I generally prefer to write things this way:

override_dh_sphinxdoc:
ifeq (,$(findstring nodocs, $(DEB_BUILD_OPTIONS)))
        sphinx-build -b html doc/source \
  $(CURDIR)/debian/python-foo-doc/usr/share/doc/python-foo-doc/html
        dh_sphinxdoc
endif

(sorry for the indentation above, lines are too short in emails)

This way, there's no need to pickup/copy the docs in doc/build, it ends
up directly in the package, ready for dh_sphinxdoc. If I need to add
some variables (for example to fix reproducibility), I can easily do it.
I will be switching to the "python3 -m sphinx" style soon, though that's
unrelated.

Over the years, I found using this method a way better than using
"python{3,} setup.py build_sphinx". I'd suggest you try my way too.

Cheers,

Thomas Goirand (zigo)