对文档做出贡献#

对文档的贡献使每个使用Pandas的人都受益。我们鼓励您帮助我们改进文档，您不必是Pandas专家也能做到这一点！事实上，文档中有一些章节在专家撰写后变得更糟糕。如果文档中的某些内容对你没有意义，在你弄清楚之后更新相关部分是确保它对下一个人有帮助的一个很好的方法。

关于Pandas的文献#

文档是用以下格式编写的 重新构造文本 ，它几乎就像用通俗易懂的英语编写的，并使用 Sphinx 。Sphinx文档具有出色的 introduction to reST 。查看Sphinx文档以对文档执行更复杂的更改。

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

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

    文档字符串清楚地解释了各个函数的用法，而该文件夹中的文档包含每个主题的类似教程的概述以及一些其他信息(新增功能、安装等)。

  • 文档字符串遵循Pandas的约定，基于 Numpy Docstring标准版 。请遵循 pandas docstring guide 有关如何编写正确文档字符串的详细说明，请参阅。

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

    .. 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 。当您希望选取要为其自动生成页面的方法/属性的子集时，请使用此选项。使用此模板时，应包括 Attributes 和 Methods 部分，则在类文档字符串中。看见 CategoricalIndex 举个例子。

    每种方法都应该包含在 toctree 在中的一个文档文件中 doc/source/reference 否则，狮身人面像将发出警告。

实用程序脚本 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 有关如何格式化文档字符串的详细指南，请参阅。

文档字符串中的示例(‘doctest’)必须是有效的Python代码，以确定性的方式返回所呈现的输出，并且可以由用户复制和运行。这可以使用上面的脚本进行检查，也可以在Travis上进行测试。不及格的文档测试将成为合并公关的拦路虎。查看 examples 部分，获取一些让文档测试通过的技巧和诀窍。

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

如何构建Pandas文档#

要求#

首先，您需要有一个能够构建Pandas的开发环境(请参阅 creating a development environment )。

构建文档#

那么，如何构建这些文档呢？导航到您的本地 doc/ 目录，然后运行：：

python make.py html

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

第一次构建文档时，将花费相当长的时间，因为它必须运行所有代码示例并构建所有生成的文档字符串页面。在随后的调用中，狮身人面像将尝试只构建已修改的页面。

如果要进行完全干净的构建，请执行以下操作：

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 branch, the main parts of the documentation are also built by Travis-CI. These docs are then hosted here ，另请参阅 Continuous Integration 部分。

预览更改#

一旦提交了Pull请求，GitHub Actions将自动构建文档。要查看已建站点，请执行以下操作：

  1. 等一等 CI / Web and docs 选中以完成。

  2. 单击 Details 就在它旁边。

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

上一页

营造发展环境

下一页

Pandas文档字符串指南