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

[Dmitry Shachnev]

Hi Neil,

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

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?

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.

> > 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.

(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.)

> 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.

--
Dmitry Shachnev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/python-modules-team/attachments/20161104/bd65a57c/attachment-0001.sig>