创建 PyPI 友好的自述文件#
自述文件可以帮助用户了解你的项目，并且可以用来在 PyPI 上设置项目的说明。本指南帮助你创建 PyPI 友好的自述文件格式，并将自述文件包含在你的包中，以便它显示在 PyPI 上。
创建自述文件#
Python 项目的自述文件通常命名为 README、README.txt、README.rst 或 README.md。
为了让你的自述文件在 PyPI 上正确显示，请选择 PyPI 支持的标记语言。PyPI 的自述文件渲染器支持的格式是
纯文本
reStructuredText（不带 Sphinx 扩展）
Markdown（默认情况下为 GitHub 风味的 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（用于 reStructuredText）或 text/markdown。
注意
如果你使用 GitHub 风味的 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 风格的 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 的原始源代码。
请注意，文档字符串中使用的 Sphinx 扩展，例如 指令 和 角色（例如，“:py:func:`getattr`”或“:ref:`my-reference-label`”），此处不允许使用，并且会导致错误消息，如“Error: Unknown interpreted text role "py:func".”。
您可以在上传之前检查 README 中是否存在标记错误，如下所示