Bits from the Sphinx maintainer

[Jakub Wilk <jwilk@debian.org>]

* Jakub Wilk <jwilk@debian.org>, 2011-05-20, 22:09:
> I'm pondering on implementing further changes in python-sphinx that 
> would allow us to fix this kind of breakage more easily in the future.  
> I'll write a separate mail about this... some day. ;)

In python-sphinx 1.0.7+dfsg-1 I made a few important changes:

1) There is now an integration test suite run at build time, which 
verifies that Sphinx JavaScript code still works.

2) The JavaScript code has been moved into a separate package, 
libjs-sphinxdoc.

3) There is a new helper tool, dh_sphinxdoc, which helps with packaging 
Sphinx-generated documentation. More specifically:
- it does a few sanity checks (e.g. for missing files that are 
needed for the JavaScript to work);
- it replaces known *.js files with symlinks to files to
/usr/share/javascript/sphinxdoc/ and generates ${sphinxdoc:Depends}
substitution variable;
- removes some cruft (.doctree/, .buildinfo).

If your package builds documentation using Sphinx, I highly recommend 
you to stop creating jquery.js symlink with dh_link (or such) and use 
dh_sphinxdoc instead. This is the only future-proof way to have 
fully-functional, policy compliant package with Sphinx-built 
documentation.

--
Jakub Wilk