[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 +, 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


signature.asc
Description: PGP signature
___
Python-modules-team mailing list
Python-modules-team@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/python-modules-team

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

[Neil Williams]

On Thu, 3 Nov 2016 22:06:17 +0300
Dmitry Shachnev  wrote:

> Hi Neil,
> 
> On Thu, Nov 03, 2016 at 06:37:23PM +, 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/



pgpE1xEh7ySGt.pgp
Description: OpenPGP digital signature
___
Python-modules-team mailing list
Python-modules-team@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/python-modules-team

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

[Dmitry Shachnev]

Hi Neil,

On Thu, Nov 03, 2016 at 06:37:23PM +, 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 […]

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

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.

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.

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

--
Dmitry Shachnev


signature.asc
Description: PGP signature
___
Python-modules-team mailing list
Python-modules-team@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/python-modules-team

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

[Neil Williams]

reopen 836248
found 836248 1.4.8-1
thanks

I came across this because I now get warnings:
dpkg-gencontrol: warning: package lava-server-doc: unused substitution variable 
${sphinxdoc:Built-Using}

I worked out I could use this line in debian/control:

Built-Using: python-sphinx-bootstrap-theme, ${sphinxdoc:Built-Using}

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)

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})

to generate output in the package of:

 Built-Using: python-sphinx-bootstrap-theme (= 0.4.8-1)

or, possibly with another substvar:

 Built-Using: python-sphinx-bootstrap-theme (= 0.4.8-1), python-sphinx (= 
1.4.8-1)

?

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.

Finally, can we have some documentation of how to use
${sphinxdoc:Built-Using} in man dh_sphinxdoc please?

-- 


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



pgpKnc6bTaXIW.pgp
Description: OpenPGP digital signature
___
Python-modules-team mailing list
Python-modules-team@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/python-modules-team