setup.py配置long_description时tox校验合法rst文件报错如何解决？

报错信息 #

ERROR: InvocationError for command /Users/.../.tox/check/bin/python setup.py check --strict --metadata --restructuredtext (exited with code 1)

前置排查结论 #

• README.rst、CHANGELOG.rst经多个在线rst校验工具验证合法，可正常渲染
• 替换rst文件内容为纯简单文本后报错消失，可确认问题根源为rst内容的解析规则不兼容
• 转换rst文件为unix换行格式无法解决该问题

最终解决方案 #

setuptools自带的restructuredtext校验规则比普通在线校验工具更严格，对-字符的解析存在特殊要求，按以下规则修改rst内容即可：

• 手动转义所有不在反引号包裹范围内的-字符，替换为-`
• 反引号包裹的代码、命令片段内的-无需转义

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