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

[Ximin Luo]

Ximin Luo:
> On Mon, 11 Apr 2016 13:30:40 +0200 Dmitry Shachnev <mitya57 at debian.org> wrote:
>> 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.
>>
> 
> Hi Dmitry, Gordon and I are trying to package ipywidgets [1] and are running into this issue as well.
> 
> I don't understand your explanation above. [..]

Sorry, I just read through the whole thread, now I understand what you meant by "edit the conf".

However, I still think it would be better for dh_sphinxdoc to do it, so as to avoid every packager spending the time to do it myself. Yes it's just a few lines, but I (and each new packager) would have to spend about an hour figuring out what those lines are, and testing it to make sure it works. And these lines will multiply over many packages. Some people might do it slightly differently, then the code gets more and more confusing eventually.

So, I will try to write the patch anyhow.

BTW can someone point me to some discussion/documentation on precisely how/why symlinks to directories mess with dpkg? I was not aware of this - I have added quite a lot of directory-symlinks to some of my recent JS packages, and we will likely have to do this for ipywidgets, with mathjax...

> [..] None of the config files in ipywidgets contain a specific MathJax URL, the remote URL we are getting is the default one from the sphinx.ext.mathjax extension. So we have nothing to change in our own package..
> 
> Could dh_sphinxdoc not scan the html files for <script src="$that_value"... and replace it with a link to Debian's MathJax instead? It already does some pretty sophisticated regex-based sanity checks (e.g. relating to #841141 which I filed recently) - so adding a replacement rule shouldn't be too hard right?
> 

X

-- 
GPG: ed25519/56034877E1F87C35
GPG: rsa4096/1318EFAC5FBBDBCE
https://github.com/infinity0/pubkeys.git