如何在pypi的描述页上使用markdown

前言

---

pypi.org 是存放python第三方库的官方源，所有的第三方库都需要在这上面进行上传。

和大部分代码托管仓库一样，pypi的项目详情页也支持 README 文档，但是和Github支持的markdown不一样，最开始pypi只支持一种叫rst的富文本语言，这种语言格式较md来说复杂，且极容易出错导致网页解析变成一堆奇怪的字符。

但是现在pypi也开始支持简单好用的md格式了，下面介绍如何让pypi支持md文本。我使用的打包工具是setuptool。

操作

---

示例是一个封装百度地图api的项目baidumap。

参见：

百度地图Web API Python模块
Pypi项目页

---

首先当然是编写好README.md存放在项目文件中

项目目录为：

project
│   setup.py
│   test.py
└───baidumap
	 │   README.md
     │   file011.py
     │   file012.py
     │
     └───subfolder1
         │   file111.py
         │   file112.py
         │   ...

然后我们开始编写打包脚本setup.py

# -*- coding: utf-8 -*-
#################
# setup.py
# author github@cpak00
#################

# -*- coding:utf-8 -*-
from setuptools import setup, find_packages

filepath = 'baidumap/README.md'

setup(
    name="baidumap",
    version="1.2.4",
    keywords=("baidu", "map", "api", "web"),
    description="api handle for baidu map",
    long_description=open(filepath, encoding='utf-8').read(),
    long_description_content_type='text/markdown',
    license="MIT Licence",
    url="https://github.com/cpak00/baidumap",
    author="cpak00",
    author_email="***cpak00@gmail.com",
    packages=find_packages(),
    include_package_data=True,
    platforms="any",
    install_requires=["requests"],
    data_files=[filepath])

注意事项

---

因为小编偷懒图方便，README.md 的位置使用的是 相对地址 ，这样的操作在上传和查看详情页的时候没有问题，但是会在用户安装时会报警告（执行目录不一样），有强迫症的同学可以os.path.join组合一下文件路径。

让pypi识别markdown的关键就是新的参数long_description_content_type以及data_files

• long_description_content_type 用来规定长描述的格式，设置为text/markdown就可以解析markdown格式
• data_files 用来使你的setuptool包含 markdown.md ，因为最开始pypi不支持markdown，所以setuptool不会自动包含.md后缀的文件，并且使用checkdocs也会报错（不用在意，旧工具，markdown亲测可用）

最后

---

python setup.py sdist
twine upload dist/*1.2.4*

上传完毕，现在pypi项目的详情页上就已经渲染出富文本了！