如何确保 README.rst 有效？答案

【问题标题】：How to ensure that README.rst is valid?如何确保 README.rst 有效？
【发布时间】：2017-10-11 07:54:54
【问题描述】：

我的小工具有两个版本：

https://pypi.python.org/pypi/tbzuploader/2017.11.0
https://pypi.python.org/pypi/tbzuploader/2017.12.0bug：pypi页面看起来很丑。

在上次更新中，README.rst 中的更改会发出警告：

user@host> rst2html.py README.rst  > /tmp/foo.html
README.rst:18: (WARNING/2) Inline emphasis start-string without end-string.
README.rst:18: (WARNING/2) Inline emphasis start-string without end-string.

现在 pypi 页面看起来很丑:-(

我用这个菜谱做CI，bumpversion，上传到pypi：https://github.com/guettli/github-travis-bumpversion-pypi

如何确保不再发布损坏的 README.rst？换句话说，我想避免 pypi 页面看起来很丑。

亲爱的细节爱好者：请不要查看 README.rst 中当前的特定错误。那不是问题:-)

【问题讨论】：

标签： python continuous-integration travis-ci restructuredtext

【解决方案1】：

更新

自 2018 年 9 月 21 日起，Python 打包机构建议使用替代命令 twine check。致install twine：

pip install twine
twine check dist/*

请注意twine requires readme_renderer。你仍然可以使用readme_renderer，如果你想要它的其他功能，你只需要安装它，如果你要发布到 PyPI，这无论如何都是个好主意。

来自官方 Python 打包文档，Uploading your Project to PyPI：

提示： PyPI 上使用的 reStructuredText 解析器不是 Sphinx！此外，为了确保所有用户的安全，某些类型的 URL 和指令被禁止或去除（例如，.. raw:: 指令）。在尝试上传您的分发之前，您应该检查setup.py 中提供的简短/详细描述是否有效。您可以按照pypa/readme_renderer 工具的说明执行此操作。

来自那个工具的README.rst：

要在本地检查您的详细描述，只需使用以下命令安装 readme_renderer 库：

$ pip install readme_renderer
$ python setup.py check -r -s

【讨论】：

太棒了。是的你是对的。如果 REAME 有效与否，readme_renderer 有权威的答案。谢谢！
现在我有了执行此操作的工具。我的下一步是如何调用它。到目前为止，我看到了两种方法：使用子进程或像库一样使用它。也许还有第三种方式。我不确定哪个更好。
@guettli 你在问一个单独的问题吗？如果是这样，请创建一个。否则，如果它确实解决了您的问题，请接受此答案。
此命令表示它已被弃用，取而代之的是 twine check，但没有提供有关如何安装它的完整说明。
@AlanSE 您在哪里看到了 readme_renderer 的弃用？ twine check 使用它。

【解决方案2】：

序言

我有一个自述文件，除了页面上的第一个元素（图像）之外，它不会在 PyPi 上呈现。我针对多个验证器运行该文件，并针对其他渲染对其进行了测试。它在其他任何地方都工作得很好！因此，在与它进行了长时间的、令人讨厌的斗争以及无数次版本的颠簸之后，我可以测试 PyPi 修订版，我尝试将文件减少到最低限度，然后我将从中构建它。原来第一行一直处理完，然后就什么都没有了...

解决方案

发现关于第一行的这条线索，然后我顿悟了……我所要做的就是更改文件中的行尾！我在 Windows 中编辑文件，隐式添加了 Windows 行尾。我将其更改为 Unix 风格并且（噗！）PyPi 完全渲染了文档！

咆哮...

我过去也遇到过这样的事情，但我想当然地认为 PyPi 会处理这样的跨平台问题。我的意思是 Python 的关键特性之一是跨平台！我是第一个在 Windows 中遇到这种情况的人吗？！我不欣赏这浪费的时间。

【讨论】：

也请告诉 pypi 开发者。
按照您的建议，我会考虑提交错误报告。
@BuvinJ ，您能否提供一些有关您用于更改行尾的工具的信息？
我通常在 Windows 上使用 Notepad++。转到编辑... EOL 转换。

【解决方案3】：

如果rstcheck 在您的自述文件中捕获到错误类型，您可以尝试。如果是这样，请在脚本部分中的 pytest 之后运行它。（并将其添加到您的要求中）。

【讨论】：