On Fri, 4 Nov 2016 16:12:36 +0300 Dmitry Shachnev <mity...@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/
pgpyq_ggSH0WH.pgp
Description: OpenPGP digital signature
