为文档做出贡献#

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

关于 pandas 文档#

该文档是用reStructuredText编写的，这几乎就像用简单的英语编写一样，并使用Sphinx构建。 Sphinx 文档对 reST 进行了精彩的介绍。查看 Sphinx 文档以对文档执行更复杂的更改。

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

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

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

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

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

    .. ipython:: python

    x = 2
    x**3

    将呈现为：

    In [1]: x = 2

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

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

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

    我们有两个类自动摘要模板。

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

    2. _templates/autosummary/class_without_autosummary。当您想要选择方法/属性的子集来自动生成页面时，请使用此选项。使用此模板时，您应该在类文档字符串中包含Attributesand 部分。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 上进行了测试。失败的文档测试将成为合并 PR 的障碍。检查文档字符串指南中的示例部分，了解一些让文档测试通过的提示和技巧。

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

如何构建 pandas 文档#

要求＃

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

构建文档#

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

python make.py html

然后您可以在该文件夹中找到 HTML 输出doc/build/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

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

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

构建主分支文档#

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

预览更改#

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

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

  2. 单击Details它旁边的。

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