我今天激动地宣布,PyPI支持使用Markdown编写项目描述了!这个特性是备受瞩目的,我们做了大量的工作,终于实现了这个特性。是直接的支持,而不是把Markdown转换为rST,或者是使用其他的Hack方式。
例如,这个示例项目使用了Markdown描述:
https://pypi.org/project/markdown-description-example/
这里是这个项目的源代码:
https://github.com/di/markdown-description-example
下面是为自己的项目添加Markdown描述的实现步骤:
有一个README.md
有一个README.md,并确保里面包含Markdown内容。文件后缀不必是.md(.mkdn/.markdown),后缀是什么都可以。只是你的setup.py确保会读取它并将内容设置给long_description
在setup.py中设置一个新参数
PEP566添加了一个新的元数据字段Description-Content-Type。为了给你的长描述添加内容类型,你需要把下面参数添加到setup.py中的setup函数调用中。
升级你的setuptools
为了支持上面添加的新的元数据,你需要升级你的setuptools版本到>=38.6.0。
当然你也必须确实是在使用setuptools进行打包,这意味着在你的setup.py中应该有这样一样引入语句:
构建发布源码
这一步跟以前没有区别
升级你的twine
同时你还要升级你的twine,需要版本>=1.11.0,否则设置的新的元数据不会被正确地发送给PyPI。
(–pre参数是需要的,因为目前我们需要这个参数来让twine升级到预发布版本)
上传你的发布版
这一步跟以前也一样
在pypi.org上查看你的项目
只有pypi.org能够正确地展示你的Markdown描述,以前的pypi.python.org只会将Markdown代码作为纯文本展示,不过别担心,旧的网站很快就要下线了