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>`