Contributing to the documentation#

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.

About the Xorbits documentation#

The documentation is written in reStructuredText, which is almost like writing in plain English, and built using Sphinx. The Sphinx Documentation has an excellent introduction to reST. Review the Sphinx docs to perform more complex changes to the documentation as well.

Some other important things to know about the docs:

  • The Xorbits documentation consists of two parts: the docstrings in the code itself and the docs in this folder doc/.

    The docstrings provide a clear explanation of the usage of the individual functions, while the documentation in this folder consists of tutorial-like overviews per topic together with some other information (what’s new, installation, etc).

  • The docstrings follow a Xorbits convention, based on the Numpy Docstring Standard.

  • The tutorials make heavy use of the IPython directive sphinx extension. This directive lets you put code in the documentation which will be run during the doc build. For example:

    .. ipython:: python
    
        x = 2
        x**3
    

    will be rendered as:

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

    Almost all code examples in the docs are run (and the output saved) during the doc build. This approach means that code examples will always be up to date, but it does make the doc building a bit more complex.

  • Our API documentation files in doc/source/reference house the auto-generated documentation from the docstrings. For classes, there are a few subtleties around controlling which methods and attributes have pages auto-generated.

    Every method should be included in a toctree in one of the documentation files in doc/source/reference, else Sphinx will emit a warning.

  • Xorbits leverages sphinx-intl to manage documentation in multiple languages. Currently, documentation in Chinese is supported.

Updating a Xorbits docstring#

When improving a single function or method’s docstring, it is not necessarily needed to build the full documentation (see next section).

The examples in the docstring (‘doctests’) must be valid Python code, that in a deterministic way returns the presented output, and that can be copied and run by users. A failing doctest will be a blocker for merging a PR.

Updating Xorbits documentation#

After updating the docs in this folder doc/, you also need to update the pot files. POT (portable object template), is a format generated by GNU gettext to streamline software localization and internationalization.

To update pot files, run:

make gettext

The generated pot files will be placed in the below directories: doc/source/locale/zh_CN/LC_MESSAGES/.

Translating Xorbits documentation#

Translating the documentation can greatly help non-English users and could be a great start for new contributors.

You need to update the pot files located in doc/source/locale/zh_CN/LC_MESSAGES/. An example of one such file, from Sphinx, builders.po, is given below:

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

You can build the documentation to view your changes (see next section).

How to build the Xorbits documentation#

Requirements#

First, you need to have a development environment to be able to build Xorbits (see the docs on creating a development environment).

Building the documentation#

So how do you build the docs? Navigate to your local doc/ directory in the console and run:

make html

Then you can find the HTML output in the folder doc/build/html/.

To build the docs in Chinese, run:

make html_zh_cn

Then you can find the HTML output in the folder doc/build/html_zh_cn/.

The first time you build the docs, it will take quite a while because it has to run all the code examples and build all the generated docstring pages. In subsequent evocations, sphinx will try to only build the pages that have been modified.

If you want to do a full clean build, do:

make clean
make html

Open the following file in a web browser to see the full documentation you just built:

doc/build/html/index.html

And you’ll have the satisfaction of seeing your new and improved documentation!

Building main branch documentation#

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.