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

Fri Nov 4 14:08:11 UTC 2016

On Fri, 4 Nov 2016 16:12:36 +0300
Dmitry Shachnev <mitya57 at debian.org> wrote:

> Hi Neil,
> 
> I saw your previous reply after I sent mine, sorry for that.

:-) No problem.

> On Thu, Nov 03, 2016 at 09:35:42PM +0000, Neil Williams wrote:
> > > 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)  
> 
> Alabaster comes from a separate source package, but it is the default
> theme for Sphinx. That's why I added support for it.
> 
> > 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?  
> 
> For packages using alabaster, it should list both sphinx and alabaster
> in sphinxdoc:Built-Using. For which package is it not the case?

OK, I'd missed that this is only if html_theme is alabaster, not default.

I'd tested with vmdebootstrap which produces:

 Built-Using: sphinx (= 1.4.8-1)

It's using html_theme = 'default' in doc/conf.py

A local change to alabaster produces:

 Built-Using: alabaster (= 0.7.8-1), sphinx (= 1.4.8-1)

> Sphinx should be listed there because all documentation packages
> produced by Sphinx contain i.e. _static/basic.css file, which is
> generated from basic.css_t in Sphinx source.
> 
> > > 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?  
> 
> Finding and parsing the conf.py is an even more complicate task :)
> 
> dh_sphinxdoc is not using any of Sphinx code, in fact, it is even
> written in Perl and not in Python.

OK. Makes sense with the rest of debhelper being perl too.

> > > 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.  
> 
> I did not mean duplication *within* lava-server-doc.
> 
> I meant that the files in lava-server-doc can be links to files in
> python[3]-sphinx-bootstrap-theme.
> 
> I.e. /usr/share/doc/lava-server-doc/html/v2/_static/bootstrap-2.3.2/ →
> /usr/lib/python2.7/dist-packages/sphinx_bootstrap_theme/bootstrap/static/bootswatch-2.3.2/
> 
> and /usr/share/doc/lava-server-doc/html/v2/_static/bootswatch-3.3.4/ →
> /usr/lib/python2.7/dist-packages/sphinx_bootstrap_theme/bootstrap/static/bootswatch-3.3.4/
> 
> Having such links would eliminate most of the need for using the
> Built-Using field.

I spent several hours trying to get this replacement to work. After a
number of changes to debian/rules (dh_sphinxdoc complains about missing
files if the default dh9 behaviour is allowed), dpkg refuses to replace
directories with symlinks. A preinst to try and achieve that fails
during testing - new installs are ok but upgrades from 2016.9 on jessie
remove files from the theme despite checks in the preinst that the
location is not a symlink. In the end, I have given up and the
duplication will just have to stay until I've more time to debug
upgrades from 2016.9 or someone else comes up with a fix.

(The changes are in the packaging repo, now complete with reversion commits.)

https://github.com/Linaro/pkg-lava-server/commit/b778135097db4b19d03de5f4787677f772ea4e42
https://github.com/Linaro/pkg-lava-server/commit/edbaa56dae87c1092de49f7ee59ac925c3176071

(Links for reference, I'm not expecting you to debug this, Dmitry.)

> (Also, it would be a good idea to ask sphinx-bootstrap-theme
> maintainer to use some interpreter-independent location for the
> static files, something in /usr/share, like I do with my
> python-sphinx-rtd-theme package. That would make it easier to symlink
> stuff.)

Agreed - but not right now. Have to actually get the 2016.11 release
out. I'll come back to this and file a bug. If there are things the
bootstrap theme package can do to let dh_sphinxdoc do the replacements
correctly, I'll gladly add those to the same bug report.

Anything which can help produce:

 Depends: python-sphinx-bootstrap-theme, libjs-sphinxdoc (>= 1.0)
 Built-Using: sphinx-bootstrap-theme (= 0.4.8-1), sphinx (= 1.4.8-1)

> > 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.  
> 
> I am bad at documenting things, but I will try to do my best here.

I thought I had a handle on how things like this worked - when I
actually tried to set this up, it all went wrong very quickly.
Documentation would be very helpful...

-- 

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/20161104/dff430a4/attachment.sig>