使用twine上传Python包失败：RST描述渲染错误

问题分析 #

PyPI的RST渲染器不支持raw指令，即便你排除了./docs目录、清空long_description仍提示错误，说明项目中还有其他包含raw指令的RST内容被twine检测到——大概率是根目录的README.rst，或是你修改的文档字符串（docstring）里嵌入了该指令（GitHub支持但PyPI不兼容）。

解决步骤 #

• 清理所有RST内容中的raw指令
  搜索项目内所有.rst文件（包括README.rst、模块/类/函数的docstring里的RST片段），找到.. raw::相关代码块，直接删除，或替换为PyPI支持的RST语法。比如：

  • 若用raw设置图片样式，换成RST原生的.. image::参数（如.. image:: path/to/img.png :width: 200px）
  • 若插入HTML代码，改用纯RST语法实现相同效果

• 确认setup.py的元数据配置
  检查setup.py中long_description的来源：

  • 若之前是读取README.rst，确保修改后的文件已无raw指令，再恢复读取逻辑
  • 若暂时不想处理RST，可改用Markdown格式：将README.rst重命名为README.md，然后修改setup.py：

    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    

• 用twine check验证修复结果
  修改后运行twine check dist/*，直到无任何错误提示。若仍指向某行错误，直接定位到对应文件的该行，确认残留的raw指令并清理。

内容的提问来源于stack exchange，提问作者Manuel Popp