贡献文档#

贡献文档对所有使用 pandas 的人都有益。我们鼓励您帮助我们改进文档，而且您无需成为 pandas 专家即可做到！事实上，文档的某些部分在专家编写后反而变得更糟。如果文档中的某些内容让您感到困惑，那么在您弄清楚之后更新相关部分是确保它能帮助下一个人的好方法。请访问问题页面，获取当前关于 Pandas 文档的所有未解决问题的完整列表。

关于 pandas 文档#

文档使用 reStructuredText 编写，这几乎就像用纯英语写作一样，并使用 Sphinx 构建。Sphinx 文档提供了出色的 reST 入门。您还可以查阅 Sphinx 文档以进行更复杂的文档修改。

关于文档的其他重要事项

  • pandas 文档由两部分组成：代码本身的 docstrings 和 doc/ 文件夹中的文档。

    docstrings 清晰解释了各个函数的用法，而此文件夹中的文档则包含按主题划分的教程式概述以及其他信息（新特性、安装等）。

  • docstrings 遵循基于 Numpy Docstring 标准的 pandas 约定。请遵循 pandas docstring 指南，获取如何编写正确 docstring 的详细说明。

  • 教程大量使用了 IPython directive sphinx 扩展。此 directive 允许您将代码放入文档中，这些代码将在文档构建期间运行。例如

    .. ipython:: python

    x = 2
    x**3

    将被渲染为

    In [1]: x = 2

In [2]: x**3
Out[2]: 8

    文档中几乎所有的代码示例都会在文档构建期间运行（并保存输出）。这种方法意味着代码示例将始终保持最新，但这确实使文档构建变得稍微复杂一些。

  • 我们位于 doc/source/reference 中的 API 文档文件包含从 docstrings 自动生成的文档。对于类，在控制哪些方法和属性自动生成页面方面存在一些细微之处。

    我们为类提供了两种自动摘要模板。

    1. _templates/autosummary/class.rst。当您希望为类的每个公共方法和属性自动生成页面时使用此模板。Attributes 和 Methods 部分将由 numpydoc 自动添加到类的渲染文档中。请参阅 DataFrame 作为示例。

    2. _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 参考页面）和实际的公共方法。这将识别在 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 指南中的 示例部分，获取一些使 doctest 通过的提示和技巧。

提交包含 docstring 更新的 PR 时，最好在 GitHub 评论中发布验证脚本的输出。

如何构建 pandas 文档#

要求#

首先，您需要一个开发环境才能构建 pandas（请参阅有关创建开发环境的文档）。

构建文档#

那么如何构建文档呢？导航到控制台中的本地 doc/ 目录并运行

python make.py html

然后您可以在 doc/build/html/ 文件夹中找到 HTML 输出。

第一次构建文档需要相当长的时间，因为它必须运行所有代码示例并构建所有生成的 docstring 页面。在后续调用中，sphinx 将尝试仅构建已修改的页面。

如果您想进行完全的干净构建，请执行

python make.py clean
python make.py html

您可以告诉 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

在 Web 浏览器中打开以下文件以查看您刚刚构建的完整文档 doc/build/html/index.html。

您将体验到看到新改进的文档的满足感！

构建主分支文档#

当拉取请求合并到 pandas main 分支时，文档的主要部分也由 Travis-CI 构建。这些文档随后托管在此处，另请参阅 持续集成部分。

预览更改#

提交拉取请求后，GitHub Actions 将自动构建文档。要查看构建好的网站

  1. 等待 CI / Web and docs 检查完成。

  2. 点击其旁边的 Details。

  3. 从 Artifacts 下拉菜单中，点击 docs 或 website 以下载网站的 ZIP 文件。