On Thu, 3 Nov 2016 22:06:17 +0300 Dmitry Shachnev <mity...@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/
pgpUiUNzF3H1m.pgp
Description: OpenPGP digital signature
