reStructuredText: README.rst not parsing on PyPI

问题:

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.

回答1:

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: altogether:

:code:`sentiment`

with:

`sentiment`

etc.

回答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.

回答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 .