生成一个Pypi友好的自述文件¶
自述文件可以帮助您的用户理解您的项目，并可用于在PYPI上设置项目的描述。本指南帮助您以Pypi友好格式创建自述文件，并将自述文件包含在包中，使其显示在Pypi上。
创建自述文件¶
python项目的自述文件通常命名为 README ， README.txt ， README.rst 或 README.md .
要使自述文件正确显示在Pypi上，请选择Pypi支持的标记语言。支持的格式 PyPI's README renderer 是：
纯文本
reStructuredText （无狮身人面像延伸）
Markdown (GitHub Flavored Markdown 默认情况下，或 CommonMark ）
通常将自述文件保存在项目的根目录中，与 setup.py 文件。
在包的元数据中包含自述文件¶
要将自述文件的内容作为包描述，请设置项目的 Description 和 Description-Content-Type 元数据，通常在项目的 setup.py 文件。
例如，在包的 setup.py 文件，使用 setup() 的 long_description 和 long_description_content_type .
设置的值 long_description 到自述文件本身的内容（而不是路径）。设置 long_description_content_type 接受 Content-Type -自述文件标记的样式值，例如 text/plain ， text/x-rst （用于重构文本），或 text/markdown .
注解
如果使用Github风格的降价来编写项目描述，请确保升级以下工具：
python3 -m pip install --user --upgrade setuptools wheel twine
各工具的最低要求版本如下：
setuptools >= 38.6.0
wheel >= 0.31.0
twine >= 1.11.0
建议您使用 twine 要上载项目的分发包，请执行以下操作：
twine upload dist/*
例如，请参见 setup.py 文件，它读取 README.md 作为 long_description 并将标记标识为Github风味的降价：
from setuptools import setup
# read the contents of your README file
from os import path
this_directory = path.abspath(path.dirname(__file__))
with open(path.join(this_directory, 'README.md'), encoding='utf-8') as f:
long_description = f.read()
setup(
name='an_example_package',
# other arguments omitted
long_description=long_description,
long_description_content_type='text/markdown'
)
正在验证重构文本标记¶
如果您的自述文件是用restructuredtext编写的，那么任何无效的标记都将阻止它呈现，从而导致pypi只显示自述文件的原始源文件。
注意文档字符串中使用的sphinx扩展名，例如 directives and roles （例如，“:py:func:`getattr`````或“`:ref:`my reference label````”）在这里不允许，并将导致错误消息，如“``error:unknown expressed text role”py:func“.`”。
您可以在上传前检查自述文件中的标记错误，如下所示：