为文档做贡献#
为文档做贡献对所有 pandas 用户都有益。我们鼓励您帮助我们改进文档，您不必是 pandas 专家也可以做到！事实上，有些文档部分在专家编写后反而变得更差了。如果您觉得文档中的某些内容不清楚，在弄明白后更新相应部分是确保它能帮助下一个人的好方法。请访问 issues 页面 查看目前关于 pandas 文档的所有开放问题。
关于 pandas 文档#
文档是用 reStructuredText 编写的，它几乎就像用纯英文写作，并使用 Sphinx 构建。Sphinx 文档对 reST 有很好的介绍。请参考 Sphinx 文档以对文档进行更复杂的更改。
关于文档的一些其他重要事项
pandas 文档包含两部分：代码本身的 docstrings 和此文件夹
doc/中的文档。docstrings 提供了对单个函数用法的清晰解释，而此文件夹中的文档则包含按主题的类似教程的概述以及其他一些信息（新增内容、安装等）。
docstrings 遵循 pandas 的约定，该约定基于 Numpy Docstring Standard。请遵循 pandas docstring 指南 以获取有关如何编写正确 docstring 的详细说明。
教程大量使用了 IPython directive sphinx 扩展。此指令允许您在文档中放置代码，这些代码将在文档构建期间运行。例如
.. ipython:: python x = 2 x**3
将呈现为
In [1]: x = 2 In [2]: x**3 Out[2]: 8
文档中的几乎所有代码示例都在文档构建期间运行（并保存输出）。这种方法意味着代码示例将始终是最新的，但它确实使文档构建变得更加复杂。
我们位于
doc/source/reference的 API 文档文件存储了从 docstrings 自动生成的文档。对于类，在控制哪些方法和属性具有自动生成的页面方面存在一些细微之处。我们有两个用于类的 autosummary 模板。
_templates/autosummary/class.rst。当您想为类的每个公共方法和属性自动生成一个页面时，请使用此模板。Attributes和Methods部分将由 numpydoc 自动添加到类的渲染文档中。请参阅DataFrame作为示例。_templates/autosummary/class_without_autosummary。当您想选择一个方法/属性子集来自动生成页面时，请使用此模板。使用此模板时，您应该在类 docstring 中包含Attributes和Methods部分。请参阅CategoricalIndex作为示例。
每个方法都应包含在
doc/source/reference中的一个文档文件内的toctree中，否则 Sphinx 将发出警告。
实用脚本 scripts/validate_docstrings.py 可用于获取 API 文档的 CSV 摘要。还可以验证特定类、函数或方法的 docstring 中的常见错误。摘要还会比较 doc/source/reference（用于生成 API Reference 页面）中的文档方法列表和实际公共方法。这将识别 doc/source/reference 中未实际成为类方法的文档方法，以及 doc/source/reference 中未被文档化的现有方法。
更新 pandas 的 docstring#
当改进单个函数或方法的 docstring 时，不一定需要构建完整的文档（请参阅下一节）。但是，有一个脚本可以检查 docstring（例如 DataFrame.mean 方法）
python scripts/validate_docstrings.py pandas.DataFrame.mean
此脚本将指示一些格式错误（如果存在），还会运行并测试 docstring 中包含的示例。请参阅 pandas docstring 指南 以获取有关如何格式化 docstring 的详细指南。
docstring 中的示例（“doctests”）必须是有效的 Python 代码，能够以确定性的方式返回所示的输出，并且用户可以复制并运行。这可以通过上述脚本进行检查，并且在 Travis 上也会进行测试。失败的 doctest 将成为合并 PR 的障碍。请参阅 docstring 指南中有关 示例 的部分，其中包含一些关于如何使 doctests 通过的技巧。
当进行包含 docstring 更新的 PR 时，最好在 github 上发布验证脚本的输出作为评论。
如何构建 pandas 文档#
要求#
首先，您需要有一个开发环境来构建 pandas（请参阅关于 创建开发环境 的文档）。
构建文档#
那么如何构建文档呢？在控制台中导航到您的本地 doc/ 目录并运行
python make.py html
然后您可以在 doc/build/html/ 文件夹中找到 HTML 输出。
首次构建文档时，将花费相当长的时间，因为它需要运行所有代码示例并构建所有生成的 docstring 页面。在随后的调用中，sphinx 将尝试仅构建已修改的页面。
如果您想进行完整的干净构建，请执行
python make.py clean
python make.py html
提示
如果 python make.py html 以错误状态退出，请尝试运行命令 python make.py html --num-jobs=1 来识别错误原因。
您可以告诉 make.py 只编译文档的单个部分，从而大大缩短检查更改的周转时间。
# omit autosummary and API section
python make.py clean
python make.py --no-api
# compile the docs with only a single section, relative to the "source" folder.
# For example, compiling only this guide (doc/source/development/contributing.rst)
python make.py clean
python make.py --single development/contributing.rst
# compile the reference docs for a single function
python make.py clean
python make.py --single pandas.DataFrame.join
# compile whatsnew and API section (to resolve links in the whatsnew)
python make.py clean
python make.py --whatsnew
作为比较，完整的文档构建可能需要 15 分钟，但单个部分可能只需要 15 秒。随后的构建，仅处理您已更改的部分，将更快。
构建将自动使用您机器上的可用核心数量来加速文档构建。您可以覆盖此设置
python make.py html --num-jobs 4
在浏览器中打开以下文件以查看您刚刚构建的完整文档 doc/build/html/index.html。
您将欣喜地看到您全新且改进的文档！
构建主分支文档#
当 pull requests 合并到 pandas 的 main 分支时，文档的主要部分也会由 Travis-CI 构建。这些文档然后托管在 此处，另请参阅 Continuous Integration 部分。
预览更改#
提交 pull request 后，GitHub Actions 将自动构建文档。要查看构建的站点
等待
CI / Web and docs检查完成。点击旁边的
Details。在
Artifacts下拉菜单中，点击docs或website以下载 ZIP 文件格式的站点。