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.

Answer 3

I had the same problem when uploading my python module to pypi .

Later I checked the README.rst for errors using rst-lint which showed that my readme file was right. You can also use restructuredtext_link package for python to check the rst file for any errors or warnings .

I found that the problem was not in the README file but in setup.py itself.

Follow the below points while writing Readme and setup.py

• DO NOT WRITE MULTI LINE python strings for description or summary or anything that goes into the setup( ) arguments .
• Don't use relative links in the README file .(like ./path1/path2 ).
• Make sure the rst syntax is all right using a checking tool like rst-lint.
• If you have a markdown file , you can convert it to Restructured text using pandoc easily.

Make sure that you keep these in mind while writing README .