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

[Dmitry Shachnev]

Hi Sandro,

On Sat, Apr 09, 2016 at 01:27:03PM +0100, Sandro Tosi wrote:
> Is there any progress on this? I just got bitten by it:
>
> E: python-cycler-doc: privacy-breach-uses-embedded-file
> usr/share/doc/python-cycler-doc/html/_modules/cycler.html You may use
> libjs-mathjax package. (https://cdn.mathjax.org/mathjax/latest/mat
> hjax.js?config=tex-ams-mml_htmlormml)
>
> a quick grep on DPMT packages, shows already scipy and networkx has to
> manually symlink the file from libjs-mathjax to their local doc dir
>
> it would be extremely helpful if sphinx could do that for us.

As I previously explained in this bug, you will have to replace the MathJax
URL in conf.py manually anyway — dh_sphinxdoc can't do that for you.

Replacing it with path to packaged MathJax.js is usually enough. If it's not
(like when you want to serve the documentation via HTTP), then you can change
the URL to something in _static/, and you need *one* line to symlink that to
packaged MathJax. Because (in my opinion) this case is quite rare, because
the solution is just one line, and also because of potential problems with
directory symlinking, I also don't think this is something that could be done
in dh_sphinxdoc.

I also thought about changing Sphinx's own default to be the packaged URL.
However, we only want it for Debian packages only, not for stuff that i.e.
upstream developers build using our Sphinx package. But then there is no safe
way to determine if Sphinx is called from Debian package build (one may not
always be using dpkg-buildpackage or even debhelper, and instead calling
sphinx-build manually from build: target in debian/rules).

Better ideas are welcome, of course.

--
Dmitry Shachnev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/python-modules-team/attachments/20160411/35d2537e/attachment.sig>