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
signature.asc
Description: PGP signature
