python - 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

历史记录：这个答案涵盖了一个不再使用的 PyPI 版本，因为它已经被一个名为Warehouse的新服务器所取代，该服务器一直在跟踪 docutils 发布时的版本（在撰写本文时，它是 0.16 ）。如果您今天遇到重组文本渲染的问题，这个答案将不再帮助您。

原始答案如下。

---

您正在使用较新的文本角色，:code:.

PyPI 似乎只支持 docutils 0.8，code并直接添加到 PyPI 解析器，这code-block意味着:code:不支持。

GitHub 使用较新版本的 docutils（0.9 或 0.10）。

完全删除:code:角色，因此替换：

:code:`sentiment`

和：

`sentiment`

等等

Answer 2

对于我最近上传的一个包README.rst，问题是我们的贡献指南中的一个相对链接（不是页内链接） ，它在 GitHub 上呈现良好，但在 PyPI 上呈现失败。

为了解决这个问题，我暂时把链接变成了绝对链接，叫做

python setup.py register

更新元数据并在不提交更改的情况下撤消更改。

Answer 3

将我的 python 模块上传到 pypi 时，我遇到了同样的问题。

后来我检查了README.rst中的错误，rst-lint这表明我的自述文件是正确的。您还可以使用restructuredtext_linkpackage for python 检查 rst 文件是否有任何错误或警告。

我发现问题不在 README 文件中，而在setup.py本身。

在编写自述文件和 setup.py 时遵循以下几点

• 不要为描述或摘要或任何进入 setup() 参数的内容编写多行 Python 字符串。
• 不要在 README 文件中使用相对链接。（如 ./path1/path2 ）。
• 使用 rst-lint 之类的检查工具确保 rst 语法正确。
• 如果您有一个 markdown 文件，您可以使用pandoc轻松地将其转换为 Restructured 文本。

确保在编写 README 时牢记这些。