[Python-modules-team] Bug#739300: dh_sphinxdoc: Please replace MathJax.js with links to the packaged libjs-mathjax

[Sebastian Ramacher]

Hi Dmitry

On 2014-03-02 16:39:53, Dmitry Shachnev wrote:
> I have performed some queries on codesearch.debian.net and it seems that
> currently only two packages ship embedded copy of MathJax (mcrl2 and yelp):
> 
> Your package breathe in NEW seems to be another one, and the only one using
> Sphinx. Given that you already fixes breathe, I think the impact of this
> bug is zero.

No, breathe doesn't ship an embedded copy of MathJax. My initial bug
report should have been better. Let me expand a bit:

 - breathe uses sphinx.ext.mathjax.
 - The final HTML files contain a script tag with src
   http://cdn.mathjax.org/mathjax/latest/MathJax.js per default.
 - lintian emits a privacy-breach-generic because of this [1].

In breathe I replaced the MathJax URL with the full path of MathJax.js
as provided by libjs-mathjax. It gets rid of the lintian warning and
works if one views the HTML files directly in a local browser. After a
discussion with Stuart Prescott in #d-python I learned that this is
wrong: if the documentation is served via a web server, the tex formulas
are not rendered anymore.

So I've tried to fix this in other ways. Simply creating a symlink for
MathJax.js in _static is unfortunately not enough as the other files
needed by MathJax won't be found. Using dh_linktree to create a symlink
tree instead I ended up with 30k-ish symlinks in the package. That's
just too much for a documentation displaying one or two formulas. If I'm
not missing another possible solution, this only leaves creating a
symlink to /usr/share/javascript/mathjax in _static [2].

I guess I was hoping for a magical solution from dh_sphinxdoc as
sphinx.ext.mathjax is provided by sphinx and already has some code in
place to replace javascript libraries with the ones provided by other
packages. So that all of this could be handled in one place instead of
every package that uses sphinx.ext.mathjax.

Cheers

[1] http://lintian.debian.org/tags/privacy-breach-generic.html lists
some packages that emit the warning for multiple possible MathJax
URLs. I didn't check if they use sphinx to generate the documentation,
but the list contains some python-*-doc which are the most likely
candidates that could be using sphinx and sphinx.ext.mathjax.

[2] Symlinking to directories always leaves a sour taste in my mouth.
Hello unhandled symlink to directory conversions and friends.
-- 
Sebastian Ramacher
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/python-modules-team/attachments/20140304/55506b91/attachment-0001.sig>