Welcome to the documentation for RLinf! This README provides detailed instructions on how to generate the project documentation locally using Sphinx. It covers the entire process, from setting up your environment to building and viewing the documentation. Additionally, it includes information on cleaning the build directory and an introduction to Sphinx and reStructuredText (RST).

Every time you open a new terminal session to work on the documentation, run these commands to set the locale for Sphinx:

export LC_ALL=C.UTF-8
export LANG=C.UTF-8

These ensure proper character encoding with the C.UTF-8 locale.

Note: Repeat this step for every new terminal session before building the documentation.

cd <path_to_RLinf_project_root>  # Navigate to the RLinf project root directory
bash requirements/install.sh docs --venv .docs-venv
source .docs-venv/bin/activate

With your environment ready, build the documentation using Sphinx. Source files are in the source directory, and output HTML files go to build/html.

You can simply run the following command to build the English docs and open a server for preview and live reloading:

bash autobuild.sh

To build the Chinese docs, run this:

bash autobuild.sh zh

To build without running the preview server, run this command:

sphinx-build source-en build/html # change to source-zh for Chinese docs

After building, view the documentation in your browser.

1. Go to the build/html directory.
2. Open index.html in your browser.

Or, serve it with a Python HTTP server:

cd build/html
python -m http.server 8000

Visit http://localhost:8000 in your browser.

Running sphinx-autobuild automatically hosts the documentation at http://localhost:8000. Open this URL to view it with live reloading.

To remove generated files and start fresh, clean the build directory:

make clean

This deletes the build directory and its contents.

Sphinx uses reStructuredText (RST), a simple yet powerful markup language for documentation.

RST grammar