为文档做贡献#

为文档做贡献使每个使用 pandas 的人都受益。我们鼓励您帮助我们改进文档，而且您不必是 pandas 的专家！事实上，有些部分由专家编写的文档反而变得更糟。如果在文档中有某些内容对您来说没有意义，那么在您弄清楚之后更新相关部分是确保它帮助下一个人的好方法。请访问 问题页面 以获取目前关于 pandas 文档的开放问题的完整列表。

关于 pandas 文档#

文档是用 reStructuredText 编写的，这几乎就像用纯英语写作一样，并且使用 Sphinx 构建。Sphinx 文档有一个优秀的 reST 介绍。查看 Sphinx 文档以对文档进行更复杂的更改。

关于文档需要了解的一些其他重要事项：

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

    docstrings 提供了对各个函数用法的清晰解释，而本文件夹中的文档则由每个主题的教程式概述以及一些其他信息（新功能、安装等）组成。

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

  • 教程大量使用了 IPython 指令 sphinx 扩展。这个指令允许你在文档中放置代码，这些代码将在文档构建期间运行。例如:

    .. ipython:: python

    x = 2
    x**3

    将被渲染为:

    In [1]: x = 2

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

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

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

    我们有两个用于类的 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摘要。还可以验证特定类、函数或方法的docstring中的常见错误。摘要还会比较在 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。

而且你会对自己新改进的文档感到满意！

构建主分支文档#

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

预览更改#

一旦提交了拉取请求，GitHub Actions 将自动构建文档。要查看构建的站点：

  1. 等待 CI / Web 和文档 检查完成。

  2. 点击它旁边的 Details。

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