Documentation

OpenBox uses sphinx to generate the documentation. It supports reStructuredText(.rst) and Markdown(.md) as the source files.

For markdown parser, recommonmark is deprecated and myst-parser is used instead.

Documentation is hosted on Read the Docs and is built automatically when a commit is pushed to the master branch.

Currently, the sphinx-hoverxref extension requires Read the Docs as backend to work properly. It cannot be used in local build. And if you want to use GitHub Pages to host the documentation, you need to remove this extension.

Official Guides

• sphinx: https://www.sphinx-doc.org/en/master/usage/quickstart.html

• myst-parser: https://myst-parser.readthedocs.io/

  • myst-parser syntax: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#

  • To include-markdown-files-into-an-rst-file: https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-markdown-files-into-an-rst-file (The parser option requires docutils>=0.17)

• readthedocs: https://docs.readthedocs.io/

Configuration

Sphinx configuration file is docs/en/conf.py.

Read the Docs configuration file is .readthedocs.yaml. (For Chinese version, it is docs/zh_CN/.readthedocs.yaml.)

The requirements for building the documentation are listed in requirements/dev/docs.txt.

Please look through these files carefully.

Build the Documentation Locally

Install the requirements via pip install -r requirements/dev/docs.txt.

Before pushing your changes, you should build the documentation locally to make sure it looks good:

cd docs/en
make html

Open build/html/index.html or type open build/html/index.html in the terminal to view the documentation.

To remove the build files, run make clean or simply delete the build directory.

Remember to include build in .gitignore to avoid committing the build files.

For Read the Docs

Project page: https://readthedocs.org/projects/open-box/

Project page (Chinese version): https://readthedocs.org/projects/open-box-zh-cn/

The documentation is currently hosted on Read the Docs

Sync with GitHub

The documentation is built automatically when a commit is pushed to the master branch.

If the documentation is not updated after a push, please check the “Integrations” (https://readthedocs.org/dashboard/open-box/integrations/) and “Webhooks” in the repository settings on GitHub.

If the integration cannot be added successfully, you need to remove the Read the Docs integration and webhooks (if any), remove the webhooks in the repository settings on GitHub, and then manually add the webhook in GitHub. Tutorial: https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html

Multi-language Support

The documentation supports multi-language.

All source files are located in docs/en and docs/zh_CN.

We created multiple Read the Docs projects for different languages. The English version open-box is the main project. The Chinese version open-box-zh_CN is a translation project. The translation project is linked to the main project in the Translations section of the main project settings.

For sphinx-hoverxref

Currently, the sphinx-hoverxref extension requires Read the Docs as backend to work properly. It cannot be used in local build. And if you want to use GitHub Pages to host the documentation, you need to remove this extension.

To use sphinx-hoverxref in Markdown(.md) files, instead of using [Link Text](file path), use the following syntax:

{ref}`Link Text <directory/filename_without_suffix:title>`

For example:

{ref}`Installation Guide <installation/installation_guide:installation guide>`