• 微信公众号:美女很有趣。 工作之余,放松一下,关注即送10G+美女照片!

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

互联网 diligentman 3小时前 3次浏览

前面雷学委给大家缕一缕了如何开发一个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库发生错误如下:
【pypi开源项目文档】终极秘诀应对rst解析错误:The description failed to render in the default format of reStructuredText

第一步 认识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

其他错误

比如下面的内容也会报错:
【pypi开源项目文档】终极秘诀应对rst解析错误:The description failed to render in the default format of reStructuredText

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

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


喜欢 (0)