reStructuredText: README.rst not parsing on PyPI

Question

I have a Python project that is hosted on both Github and PyPI.

On Github: https://github.com/sloria/TextBlob/blob/master/README.rst

On PyPi: https://pypi.python.org/pypi/textblob

My README.rst doesn't seem to be formatting correctly on PyPI, but it looks fine on Github.

I have already read this, but I don't have any in-page links, so that's not the problem.

Answer 1

Historical note: this answer covered a release of PyPI that is no longer used, as it has since been replaced by a new server called Warehouse, which has been tracking docutils releases as they come out (which at the time of this note, was 0.16). If you are having issues with Restructured Text rendering today, this answer will no longer help you.

Original answer follows.

---

You are using a newer text role, :code:.

PyPI appears to only support docutils 0.8, with code and code-block added to the PyPI parser directly, which means that :code: is not supported.

GitHub uses a newer version of docutils (0.9 or 0.10).

Remove the :code: role altogether, so replace:

:code:`sentiment`

with:

`sentiment`

etc.

Answer 2

For a package I uploaded recently, the issue was a relative link (not an in-page link) in the README.rst to our contribution guidelines, which renders fine on GitHub, but trips up rendering on PyPI.

To fix this, I temporarily turned the link into an absolute link, called

python setup.py register

to update the metadata and backed out the change without committing it.