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

[Dmitry Shachnev]

Hi Sebastian,

On Tue, 4 Mar 2014 19:48:11 +0100, Sebastian Ramacher wrote:
> 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.

Thanks for explaining me why simply changing the URL won’t work.
But is that really a popular use-case?

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

But package maintainers will still need to patch the code to use the
local path. I think writing one line to debian/rules is easy enough
if you have already written the patch :)

Anyway, I think it is possible to implement this algorithm in
dh_sphinxdoc:

| If an HTML file in a package references _static/mathjax/MathJax.js in
| ‘script’ tag, and neither of _static/mathjax and _static/mathjax/MathJax.js
| is already a symlink, then replace the _static/mathjax directory with
| a symlink to /usr/share/javascript/mathjax/.

Will that work for you?

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

Thanks, I will file some bugs on these packages.

--
Dmitry Shachnev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: OpenPGP digital signature
URL: <http://lists.alioth.debian.org/pipermail/python-modules-team/attachments/20140306/5b01c169/attachment-0001.sig>