参与 Xorbits 文档开发#

Contributing to the documentation benefits everyone who uses Xorbits. We encourage you to help us improve the documentation, and you don’t have to be an expert on Xorbits to do so! In fact, there are sections of the docs that are worse off after being written by experts. If something in the docs doesn’t make sense to you, updating the relevant section after you figure it out is a great way to ensure it will help the next person. Please visit the issues page for a full list of issues that are currently open regarding the Xorbits documentation.

关于 Xorbits 文档#

Xorbits 的文档是 reStructuredText 格式，几乎就像用普通英语写作一样，使用 Sphinx 构建。Sphinx 的文档中有 reST 教程 。请查看该文档，以了解文档操作。

以下是有关文档的其他重要事项：

  • Xorbits 文档由两部分组成：代码本身的 docstrings 和位于 doc/ 文件夹中的文档。

    docstrings 为各个函数的使用方式提供了清晰的解释，而位于此文件夹中的文档则由一个个主题教程以及一些其他信息（新功能介绍、安装等）组成。

  • docstrings 遵循 Xorbits 的规范，由 Numpy Docstring 规范 演化而来。

  • 教程中大量使用了 sphinx 的 IPython directive 插件。IPython directive 允许你把代码嵌入文档，并在构建文档时运行这部分代码。举例来说：

    .. ipython:: python

    x = 2
    x**3

    会显示为：

    In [1]: x = 2

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

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

  • 我们的 API 文档文件位于 doc/source/reference，包含从 docstrings 自动生成的文档。对于一个类，我们要控制哪些方法和属性需要自动生成文档页面。

    每个方法都应对应 doc/source/reference 下的一个文件，并被包含在 toctree 中，否则 Sphinx 会提示警告。

  • Xorbits利用 sphinx-intl 来管理多种语言的文档。目前支持中文文档。

更新 Xorbits docstring#

改进某个函数或方法的 docstring 后，不一定要从头构建文档（请参见下一节）。

docstring 中的示例必须是有效的Python代码，以确定性的方式返回所呈现的输出，可以被用户复制并运行。doctest 运行失败将阻止合并 PR。

更新 Xorbits 文档#

在更新 doc/ 目录下的文档后，你还需要更新 pot 文件。POT（portable object template）是 GNU gettext 生成的文件格式，用于软件的本地化与国际化。

运行以下命令更新 pot 文件:

make gettext

更新后的 pot 文件会出现在 doc/source/locale/zh_CN/LC_MESSAGES/。

翻译 Xorbits 文档#

翻译文档可以大大帮助非英语使用者和开发者，同时也是参与 Xorbits 的很好的起点。

你需要做的是更新 doc/source/locale/zh_CN/LC_MESSAGES/ 目录下的 pot 文件。以 Sphinx 的 builders.po 为例:

# a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

在完成翻译后，你可以重新构建文档来查看你的修改（请参见下一节）。

如何构建 Xorbits 文档#

前置条件#

首先你需要一个能够构建 Xorbits 的开发环境（请见 配置开发环境）。

构建文档#

那么如何构建文档？在命令行中切换到 doc/ 目录，并执行:

make html

你可以在 doc/build/html/ 目录下看到生成的 HTML 文件。

若想构建中文文档，执行以下命令:

make html_zh_cn

你可以在 doc/build/html_zh_cn/ 目录下看到生成的中文 HTML 文件。

第一次构建文档需要相当长的时间，因为它必须运行所有代码示例并构建所有生成的 docstring 页面。在后续调用中，Sphinx 将尝试仅构建发生修改的页面。

如果你想要从头构建，执行以下命令:

make clean
make html

在浏览器中打开以下文件来查看你构建的文档:

doc/build/html/index.html

此时你会看到你修改后或新添加的文档！是不是很有成就感呢？

构建主干分支（main）的文档#

When pull requests are merged into the Xorbits main branch, the main parts of the documentation are also built by readthedocs. These docs are then hosted here.