[Python-modules-team] Bug#818115: turn python-sphinx into an arch:any package

[Helmut Grohne]

Hi Dmitry,

On Thu, May 12, 2016 at 01:34:04PM +0300, Dmitry Shachnev wrote:
> As you can see, I don't always reply quickly. Sorry for the delay this time.

Things go slowly in cross-land anyway. Thanks for your continued
interest. :)

> > Cross building only applied to arch-dep packages. So in jansson's case,
> > it is not about libjansson-doc, but about the other packages. The only
> > part of sphinx that is actually used during a cross build of jansson
> > actually is the debhelper addon, which actually lives in sphinx-common
> > and is exposed by python-sphinx. In a very similar case, Tomasz Buchert
> > was able to move python-sphinx from Build-Depends to Build-Depends-Indep
> > in nghttp2[1]. So looking at this closer again, a potential solution for
> > sphinx could be:
> >
> >  * Mark sphinx-common Multi-Arch: foreign.
> >  * Move python-sphinx from jansson's Build-Depends to
> >    Build-Depends-Indep.
> >  * Add sphinx-common to jansson's Build-Depends.
> >
> > I didn't verify whether these changes are correct. We can try this to
> > put urgency out of the loop.
> 
> I like the plan, though the third point can be avoided if dh_sphinxdoc is
> called only during arch-indep build.

Correct. In jansson's case, the dh addon is used. In the mean time, we
fixed jansson with a wicked patch[1] that only enables the addon for
arch-indep builds. While it works, it looks fragile to me.

So whenever the dh addon is used, adding sphinx-common to Build-Depends
is the easy way.

> 161 is many packages, though in my opinion splitting the documentation into
> arch:all packages is something that should be done independently of this bug.
> Maybe we can have some kind of DD list whose packages are affected by this?
> (Or a Lintian warning, see below.)

Computing this list in an automated way is difficult, because
build-rdeps has no way of ignoring Build-Depends-Indep (even though the
underlying dose can do that, though not in unstable as Johannes just
told me).

> > Do you have any preferences on the approaches sketched above keeping in
> > mind that we will apply it to hundreds of packages?
> 
> In an ideal world, the solution looks this way:
> 
> 1) Packages shipping Sphinx documentation in arch:any packages should
> split it into arch:all packages.
> 
> 2) All packages using Sphinx should make sure dh_sphinxdoc is only called
> during arch-indep build.
> 
> For 1), maybe we can have a Lintian warning for that?
> (i.e. sphinx-documentation-in-architecture-dependent-package)

This is not as clear cut. Sometimes documentation is small. We tend to
not split out every single bit of documentation into arch:all packages.
To the contrary, manual pages tend to be included with the main package.
I do not see consensus for this increase in the number of binary
packages.

> For 2), this means packages having both arch-dep and arch-indep packages won't
> be able to use --with sphinxdoc because sphinxdoc.pm sequence won't be present
> during arch:indep build. We can recommend packages to insert it manually then,
> like:
> 
> override_dh_installdocs-indep:
>         dh_installdocs -i
>         dh_sphinxdoc -i

If the dh addon is not to be used, you should deprecate it. I actually
find the addon useful, because it removes complexity (unless you do
[1]). In an ideal world, we would maybe say "dh $@ --with-indep sphinx"?

> Alternatively, as you suggest, such packages may build-depend on sphinx-common
> and I may mark sphinx-common as Muili-Arch: foreign. If it helps then I will
> do that.

It's the simplest workaround that I see. Of course, people need to
remember to Build-Depend on sphinx-common to use the addon, which is
complexity of its own. If we pursue that road, we should document it
precisely (e.g. README.Debian?).

Helmut

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?att=1;bug=807848;filename=jansson_2.7-3.1.debdiff;msg=29