Add support for the math directive

[siebenkopf]

I am not sure if this is the right place to ask, but I haven't seen any valuable information that would solve my problem anywhere.

I have an issue with uploading a package on PyPI. Specifically, the .rst description of my project https://pypi.org/project/challenge.uccs/ does not render on the PyPI front page.

According to their recommendation: https://packaging.python.org/guides/making-a-pypi-friendly-readme/ I installed readme_renderer version 21.0 via pip. When I run the renderer on my local copy of the project, I get the message:

$ python setup.py check -r -s
running check
The project's long description is valid RST.

So, there is no error message here, I don't see any error message when uploading to PyPI.

Since all the required information should be online (just download the package that I pointed to), maybe you can help me in assessing why the PyPI page does not render.

Thanks for your help in advance.
Manuel

[di]

This is a bit mysterious to me, I agree that the description seems like valid rST.

On first glance this looks like pypi/warehouse#2718, but issuing a purge for the page does not result in a rendered description.

@theacodes Any ideas why this particular description might be failing?

[theacodes]

I'm thinking the math directive might a culprit. I'm taking a look now.

[theacodes]

Yep. It's the math directive. A warning is emitted, but I'm not sure why that's not getting to python setup.py check.

[theacodes]

Okay, mystery solved. This package contains a docutils.conf file that has the following:

[html4css1 writer]
math-output: mathjax
             https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js

which squelches the error the Warehouse sees when trying to render this file:

line : Warning: No MathJax URL specified, using local fallback (see config.html)

So we either need to (1) support math or (2) ignore local docutils.conf.

[dstufft]

We should probably ignore the local conf either way. Whether we support math or not is another question.

…

Sent from my iPhone

On Aug 1, 2018, at 4:06 PM, Thea Flowers ***@***.***> wrote: Okay, mystery solved. This package contains a docutils.conf file that has the following: [html4css1 writer] math-output: mathjax https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js which squelches the error the Warehouse sees when trying to render this file: line : Warning: No MathJax URL specified, using local fallback (see config.html) So we either need to (1) support math or (2) ignore local docutils.conf. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[siebenkopf]

Actually, I have added the docutils.conf in order to suppress the warning (I don't remember where I read that I should do this). However, the docutils.conf is also part of the python package uploaded to PyPI (it is mentioned in the MANIFEST.in).

Apparently, PyPI does not use this file when rendering the documentation. I am not sure, though, how I would fix the mathjax issue otherwise. Do you have any idea?

[jonas-eschle]

Are there any updates on this issue? We also seem to have hit it. :math: directive in README.rst let's the rendering fail (as it seems) and gives the same warning as above.

[ankostis]

Why not file an issue at warehouse so as to comply with the setting in the docutils.conf file, if it is present at the root of some package?