pypi开源项目文档终极秘诀应对rst解析错误：The description failed to render in the default format of reStructuredText(代

Posted 2021-09-26 雷学委

前面雷学委给大家缕一缕了如何开发一个python库并导入运行, 基本完成了一个初步的库，还支持了命令行工具的发布。

本文旨在提供一个通用解决方案，适应所有场景的结局RST文件渲染错误！

特别是新手在发布开源项目的时候容易遇到这个问题：

#比如这个错误，学委也会遇到。
The description failed to render in the default format of reStructuredText. See https://pypi.org/help/#description-content-type for more information.

当然，作为开发老兵有时候也会遇到，因为一不小心rst格式的文件内容非常敏感，有时候不经常敲这个，敲错了就报错了。

上传pypi库发生错误如下：

第一步 认识reStructuredText

reStructuredText 是一种文本，常用在python项目中，用于对项目或者是程序模块进行解释说明。
很多项目也配套了rst文件，然后用rst文件生成项目文档。

简单理解就是一种文本，里面可以用标记符号来表示段落，代码，超链接，也可以加上样式。

第二步 认识错误

错误的根本原因是rst的内容不符合标准。

很多工具支持rst文件可视化，看起来好好的，但是穿到pypi上面就报错了。

下面细讲。

标题格式错误了

大标题格式错误

===================
pypi_seed
===================

和这种格式的章节标题

----------------
Further discussion / 更多使用问题
----------------

Please raise PR or find the tencent group chat : https://jq.qq.com/?_wv=1027&k=ISjeG32x

第三步 动手解决

上面两个错误都是PyCharm上面RST可视化工具不会识别的。
大标题的格式换成下面的可以正常通过解析

pypi_seed
=========

章节标题参考下面的格式：

Further discussion / 更多使用问题
--------------------------

Please raise PR or find the tencent group chat : https://jq.qq.com/?_wv=1027&k=ISjeG32x

其他错误

比如下面的内容也会报错：

因为章节标题过长了， 改短一点。重新提交。

bash
Further discussion / 更多
--------------------------

rst 文件支持很多格式，也不可能一个一个罗列。

下面是通用方法。

上面都解决不了：直接找个开源项目参考

有时候自己的rst文件改半天都不行。

这个时候只能化整为零了。

找一个开源的项目的README.rst 文件来参考：

https://raw.githubusercontent.com/py4ever/pypi_seed/main/README.rst

或者gitee上面的：

https://gitee.com/py4ever/pypi_seed/raw/main/README.rst

安装里面的内容修改自己的rst文件。

小技巧01

分段修改，起个新文件贴进去一段一段追加，直到最终生成自己想要的rst文件。

小技巧02

先写成markdown，在用工具转： https://cloudconvert.com/md-to-rst

总结

很多开源的python项目中都配套了README.rst, 都可以去参考，举一反三！

编程问题没办法都写文档解释透，代码在变化，技术在变化，唯一需要我们的就是多动动脑，找对的例子参考。

本文参考的开源项目地址在这里：Pypi-Seed on Github

喜欢Python的朋友，请关注学习学委的专栏 Python基础专栏 or Python入门到精通大专栏

持续学习持续开发，我是雷学委！
编程很有趣，关键是把技术搞透彻讲明白。
创作不易，请关注收藏点赞，或者留下评论打打气！

参考链接：

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html