为文档做贡献#

为文档做贡献使所有 pandas 用户受益。我们鼓励您帮助我们改进文档，您不必是 pandas 专家也可以做到！事实上，有些文档部分在由专家编写后反而变得更糟。如果您觉得文档中的某些内容无法理解，在弄清楚之后更新相关部分是确保它能帮助下一个人的好方法。请访问 issues page ，查看当前关于 Pandas 文档的所有未解决 issues。

关于 pandas 文档#

文档是用 reStructuredText 编写的，它几乎就像用纯英文书写一样，并使用 Sphinx 构建。Sphinx 文档有一个关于 reST 的优秀 introduction to reST 。请参考 Sphinx 文档以进行更复杂的文档更改。

关于文档，还有一些其他重要的事情需要了解：

  • pandas 文档包含两部分：代码本身的文档字符串和 doc/ 文件夹中的文档。

    文档字符串提供了对单个函数用法的清晰解释，而此文件夹中的文档则包含每个主题的类似教程的概述以及一些其他信息（例如，新增内容、安装等）。

  • 文档字符串遵循基于 Numpy Docstring Standard 的 pandas 约定。请参阅 pandas docstring guide 文档字符串指南，了解编写正确文档字符串的详细说明。

  • 教程大量使用了 IPython directive 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 示例。

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

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

更新 pandas 文档字符串#

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

python scripts/validate_docstrings.py pandas.DataFrame.mean

此脚本将指示一些格式错误（如果存在），还会运行并测试文档字符串中包含的示例。请参阅 pandas docstring guide 文档字符串指南，了解有关如何格式化文档字符串的详细指南。

文档字符串中的示例（“doctests”）必须是有效的 Python 代码，能够以确定性方式返回呈现的输出，并且用户可以复制并运行。这可以通过上述脚本进行检查，并且也在 Travis 上进行测试。失败的 doctest 将是合并 PR 的障碍。请参阅文档字符串指南中的 examples 部分，了解有关使 doctests 通过的一些技巧。

当进行包含文档字符串更新的 PR 时，最好在 github 的评论中发布验证脚本的输出。

如何构建 pandas 文档#

要求#

首先，您需要有一个开发环境来构建 pandas（请参阅 creating a development environment 文档）。

构建文档#

那么如何构建文档呢？在控制台中导航到您的本地 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。

您将满意地看到您新改进的文档！

构建主分支文档#

当 pull requests 合并到 pandas 的 main 分支时，文档的主要部分也会由 Travis-CI 构建。这些文档随后会 here 托管，另请参阅 Continuous Integration 部分。

预览更改#

提交 pull request 后，GitHub Actions 将自动构建文档。要查看构建后的站点：：

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

  2. 点击其旁边的 Details。

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

On this page
显示源代码