Building Rebel Documentation with Sphinx

This website is created by converting Rebel Documentation's .rst files to .html. This is done automatically every time an .rst file is updated via a Pull Request. For more information on updating Rebel Documentation, see Contributing to the documentation. The automatic build generated by a Pull Request allows you to see the effect of the changes. However, if you want to see the effect of the changes before submitting a Pull Request, you can build Rebel Documentation locally.

This page explains how to build Rebel Documentation locally. It is divided into 4 sections:

  1. Overview of the Rebel Documentation build process

  2. Preparing your system for building Rebel Documentation locally

  3. Building and viewing Rebel Documentation locally

  4. Known issues and troubleshooting

Overview of the Rebel Documentation build process

The documentation uses the reStructuredText (reST) file format. The Rebel Documentation website is generated using Sphinx, which uses Docutils to convert the reST files to HTML.

Rebel Documentation is hosted by Read the Docs. Whenever the Rebel Documentation repository is updated, Read the Docs will update its local copy and build Rebel Documentation using Sphinx. If the build is successful, the update is published to the Rebel Documentation website.

To ensure that all updates will result in a successful build, the Rebel Documentation repository is updated via Pull Requests. Every time a Pull Request is created or updated, Read the Docs will create a local copy of the update and build it. If the build is successful, it will be published on a special build website, where the changes can be reviewed.

You can do the same thing manually, by:

  1. Creating a local copy of the Rebel Documentation repository

  2. Building Rebel Documentation locally

  3. Reviewing your changes locally

The next section will explain how to prepare your system for building Rebel Documentation locally. The following section will explain how to build and view your local copy of Rebel Documentation.

Preparing your system for building Rebel Documentation locally

To build and view a local copy of Rebel Documentation you will need to:

  1. Create a local copy of the Rebel Documentation repository

  2. Install Python3 and Pip3

  3. Install Sphinx

  4. Install Python virtual environments

  5. Create a Python virtual environment

  6. Install all the Rebel Documentation requirements

Create a local copy of the Rebel Documentation repository

If you have not done so already, we highly recommend you first learn how to edit Rebel Documentation. Although you can edit Rebel Documentation and submit Pull Requests online, we recommend you learn how to use Git and edit Rebel Documentation locally. Atlassian provides some great Git tutorials.

Ideally, you have already created a local copy of Rebel Documentation. If not, you can create a local copy by opening up a command prompt and running the following command:

git clone https://github.com/RebelToolbox/RebelDocumentation.git

This will create a folder called RebelDocumentation which will contain a copy of the Rebel Documentation repository.

Install Python3 and Pip3

Python is the programming language used by Sphinx. Pip is the package manager used by Python to install the software packages needed by Sphinx.

Python3 may already be installed on your computer. If Python is not installed, or your version of Python is out of date, install the latest version of Python. For more information go to the Python download website: https://www.python.org/downloads/

Pip is normally installed when installing Python. If Pip is not installed go to the Pip installation website for instructions on how to install it: https://pip.pypa.io/en/stable/installation/

Install Sphinx

Sphinx is used to build Rebel Documentation from the repository's .rst files. Refer to the Sphinx installation website for instructions on how to install it: https://www.sphinx-doc.org/en/master/usage/installation.html

Install Python virtual environments

We highly recommend running your Sphinx builds in a Python virtual environment.

You can use pip to install virtualenv:

pip install virtualenv

Create a Python virtual environment

To create and activate the virtual environment run the following commands:

virtualenv env
source env/bin/activate

The virtual environment called env is excluded from Rebel Documentation Git updates. Therefore, it is safe to create the env virtual environment in your local Rebel Documentation folder.

Install all the Rebel Documentation requirements

To successfully build Rebel Documentation, you need to install all the required software modules. We have created a requirements.txt file that specifies all the required software modules and versions. To install all the required software, from the command line, run:

pip install -r requirements.txt

Building and viewing Rebel Documentation locally

Preparing your system for building Rebel Documentation locally only needs to be done once. All the required software and settings are saved in your virtual environment. Therefore, it is important to remember to always activate your virtual environment.

source env/bin/activate

If you have successfully prepared your system for building Rebel Documentation, building Rebel Documentation is as simple as running:

make html

The initial build may take a long time, because the api/ folder contains hundreds of files. However, subsequent, incremental builds will be much quicker.

Once Rebel Documentation has built, you can view the local build by opening _build/html/index.html in your web browser.

Known issues and troubleshooting

If your build reports a MemoryError or EOFError, try removing the api/ folder and running make html again. This will build Rebel Documentation without the Rebel Engine API.

Warning

If you delete the api/ folder, do not use git add . when working on a pull request or the whole api/ folder will be removed when you commit.