[Python-modules-team] Bug#836248: Re-open

[Neil Williams]

On Thu, 3 Nov 2016 22:06:17 +0300
Dmitry Shachnev <mitya57 at debian.org> wrote:

> Hi Neil,
> 
> On Thu, Nov 03, 2016 at 06:37:23PM +0000, Neil Williams wrote:
> > [...]
> >
> > That results in a package containing:
> >
> >  Built-Using: python-sphinx-bootstrap-theme, sphinx (= 1.4.8-1)
> >
> > The problem with that is:
> > $ apt-cache show sphinx
> > N: Unable to locate package sphinx
> > E: No packages found
> >
> > So dh_sphinxdoc should be putting in python-sphinx (= 1.4.8-1)  
> 
> No. Let me quite the Debian Policy § 7.8 (the emphasis is mine):
> 
>   A Built-Using field must list the corresponding *source* package
> for any such binary package incorporated during the build […]

That was my error, yes.

> > Also, wasn't the original intention from the bug report that I'd be
> > able to use it as:
> >
> >  Built-Using: python-sphinx-bootstrap-theme (=
> > ${sphinxdoc:Built-Using})
> >
> > [...]
> >
> > It's the theme which adds the CSS. Having Built-Using for sphinx is
> > fine but the version of the theme is unrelated to the version of
> > sphinx.  
> 
> The original bug was asking about Alabaster, which is the default
> theme, and thus much more popular than the bootstrap theme.

The bug mentioned python3-alabaster which comes from the alabaster
source package, not sphinx. Currently at versio 0.7.8-1 - that's why I
thought it could relate to themes packaged separately from sphinx
itself. i.e.:

Built-Using: python3-alabaster (= foo)

Correcting for the misconception about binary vs source package, my
expectation of the original bug report was that the fix would allow the
package to contain:

Built-Using: alabaster (= 0.7.8-1)

python-sphinx depends on python-alabaster in unstable but not in
jessie. The source package is still separate though and building docs
using alabaster doesn't create a dependency on python-alabaster.

The current helper produces

Built-Using: sphinx (= 1.4.8-1)

That seems inaccurate to me as the files come from a dependency of
sphinx? Or is this only meant to relate to files in libjs-sphinxdoc?

> I can try to detect whether the documentation contains embedded
> CSS/JS files from any theme, but that would be quite complicated. The
> only way that comes to my mind is comparing the file names in the
> theme package (extracted from build-dependencies) and in the built
> package, and searching for *_t → * renamings.
> 
> However, this sounds like a huge hack to me, so I am not sure I want
> to do this.

The theme needs to be specified in the conf.py and the package
providing it needs to be installed for the theme to be active, isn't
there a way of mapping that instead of looking at the output files?

> In your particular case (lava-server-doc), you have the JS, CSS and
> fonts files not symlinking, which sounds like a much bigger issue for
> me. In dh_sphinxdoc, I cannot support every existing Sphinx theme, so
> you need to symlink these files manually.


> In lava-server-doc, there are > 5 MB of files that can be symlinked,
> and only two files (8.1 kB) that are generated from templates, so I
> don't even think it makes sense to care about them.

Specifically about lava-server-doc, there is duplication because we're
migrating to a whole new model. We expect to drop the v1 directory
during 2017.

> > Finally, can we have some documentation of how to use
> > ${sphinxdoc:Built-Using} in man dh_sphinxdoc please?  
> 
> Leaving this bug open for this part of your message.

Thanks. The process of building from the theme is quite opaque - it's
not clear whether Built-Using: sphinx (= 1.4.8-1) is accurate for a
package using an external theme. Some help in the manpage would be
appreciated to clarify things like which files need to be symlinked to
the theme package and why Built-Using should refer to sphinx and not
the theme.

-- 


Neil Williams
=============
http://www.linux.codehelp.co.uk/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 801 bytes
Desc: OpenPGP digital signature
URL: <http://lists.alioth.debian.org/pipermail/python-modules-team/attachments/20161103/0301736e/attachment-0001.sig>