贡献文档#

贡献文档对所有使用 pandas 的人都有益处。我们鼓励您帮助我们改进文档，而且您不必是 pandas 专家也能做到！事实上，文档中有些部分在由专家编写后反而变得更糟。如果文档中的某些内容您不理解，那么在您弄清楚之后更新相关部分是确保它能帮助下一个人的好方法。请访问议题页面，查看当前与 Pandas 文档相关的所有开放议题列表。

关于 pandas 文档#

文档使用 reStructuredText 编写，这几乎就像写纯英语一样，并使用 Sphinx 构建。Sphinx 文档提供了一份优秀的 reST 入门指南。您也可以查阅 Sphinx 文档，以便对文档进行更复杂的修改。

关于文档的一些其他重要事项

  • pandas 文档由两部分组成：代码本身的文档字符串以及此文件夹 doc/ 中的文档。

    文档字符串清晰解释了单个函数的使用方法，而此文件夹中的文档则包含按主题分类的教程式概述以及其他一些信息（新特性、安装等）。

  • 文档字符串遵循 pandas 约定，该约定基于 Numpy 文档字符串标准。请遵循 pandas 文档字符串指南，获取如何编写正确文档字符串的详细说明。

  • 教程大量使用了 IPython 指令 的 sphinx 扩展。该指令允许您在文档中放置代码，这些代码将在文档构建过程中运行。例如

    .. ipython:: python

    x = 2
    x**3

    将被渲染为

    In [1]: x = 2

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

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

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

    我们有两个用于类的 autosummary 模板。

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

    2. _templates/autosummary/class_without_autosummary。当您想选择方法/属性的子集来自动生成页面时，请使用此模板。使用此模板时，您应在类文档字符串中包含 Attributes 和 Methods 部分。请参阅 CategoricalIndex 获取示例。

    每个方法都应该包含在 toctree 中，位于 doc/source/reference 文件夹中的某个文档文件中，否则 Sphinx 将发出警告。

实用脚本 scripts/validate_docstrings.py 可用于获取 API 文档的 csv 摘要。它还可以验证特定类、函数或方法的文档字符串中的常见错误。该摘要还比较了 doc/source/reference 文件夹中文件中记录的方法列表（用于生成 API 参考页面）与实际的公共方法。这将识别出在 doc/source/reference 中记录但并非实际类方法的方法，以及存在但未在 doc/source/reference 中记录的方法。

更新 pandas 文档字符串#

在改进单个函数或方法的文档字符串时，不一定需要构建完整文档（参见下一节）。但是，有一个脚本可以检查文档字符串（例如针对 DataFrame.mean 方法）

python scripts/validate_docstrings.py pandas.DataFrame.mean

此脚本将指出可能存在的格式错误，并运行和测试文档字符串中包含的示例。请查看 pandas 文档字符串指南，获取关于如何格式化文档字符串的详细指南。

文档字符串中的示例（“doctests”）必须是有效的 Python 代码，以确定性的方式返回所示输出，并且用户可以复制并运行。这可以使用上面的脚本进行检查，并在 Travis 上进行测试。失败的 doctest 将成为合并 PR 的阻碍。请查看文档字符串指南中的示例部分，获取一些关于如何使 doctests 通过的技巧。

在提交包含文档字符串更新的 PR 时，最好将验证脚本的输出作为评论发布到 github 上。

如何构建 pandas 文档#

要求#

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

构建文档#

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

python make.py html

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

第一次构建文档会花费相当长的时间，因为它必须运行所有代码示例并构建所有生成的文档字符串页面。后续的构建中，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

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

您将看到您新改进的文档，并感到满意！

构建 main 分支文档#

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

预览更改#

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

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

  2. 点击其旁边的 Details。

  3. 从 Artifacts 下拉列表中，点击 docs 或 website 以下载站点 ZIP 文件。