创建 PyPI 友好的 README¶
README 文件可以帮助您的用户理解您的项目，并可用于在 PyPI 上设置您的项目描述。本指南将帮助您以 PyPI 友好的格式创建 README，并将您的 README 包含在您的包中，以便它出现在 PyPI 上。
创建 README 文件¶
Python 项目的 README 文件通常命名为 README、README.txt、README.rst 或 README.md。
为了使您的 README 在 PyPI 上正确显示，请选择 PyPI 支持的标记语言。PyPI 的 README 渲染器支持的格式有：
纯文本
reStructuredText（不含 Sphinx 扩展）
Markdown（默认为GitHub Flavored Markdown，或CommonMark）
通常，您会将 README 文件保存在项目的根目录中，与 setup.py 文件在同一目录中。
将您的 README 包含在包的元数据中¶
要将您的 README 内容作为包描述包含进来，请设置项目的 Description 和 Description-Content-Type 元数据，通常在项目的 setup.py 文件中。
例如，要在包的 setup.py 文件中设置这些值，请使用 setup() 的 long_description 和 long_description_content_type。
将 long_description 的值设置为 README 文件本身的内容（而不是路径）。将 long_description_content_type 设置为您的 README 文件标记可接受的 Content-Type 风格的值，例如 text/plain、text/x-rst（对于 reStructuredText）或 text/markdown。
注意
如果您正在使用 GitHub Flavored Markdown 编写项目描述，请确保升级以下工具：
python3 -m pip install --user --upgrade setuptools wheel twine
py -m pip install --user --upgrade setuptools wheel twine
相关工具的最低要求版本是：
setuptools >= 38.6.0wheel >= 0.31.0twine >= 1.11.0
建议您使用 twine 上传项目的分发包。
twine upload dist/*
例如，请参阅此 setup.py 文件，它将 README.md 的内容读取为 long_description，并将标记标识为 GitHub Flavored Markdown：
from setuptools import setup
# read the contents of your README file
from pathlib import Path
this_directory = Path(__file__).parent
long_description = (this_directory / "README.md").read_text()
setup(
name='an_example_package',
# other arguments omitted
long_description=long_description,
long_description_content_type='text/markdown'
)
验证 reStructuredText 标记¶
如果您的 README 是用 reStructuredText 编写的，任何无效的标记都将阻止其渲染，导致 PyPI 只显示 README 的原始源。
请注意，在 docstring 中使用的 Sphinx 扩展，例如指令和角色（例如，“:py:func:`getattr`”或“:ref:`my-reference-label`”），此处不允许使用，并将导致诸如“Error: Unknown interpreted text role "py:func".”的错误消息。
您可以在上传前按如下方式检查 README 中的标记错误：