About OBR documentation

How to write the Documentation

To create the Documentation, SPHINX framework is used (https://www.sphinx-doc.org).

Installation

To use Sphinx, we need Python 3. To reduce clutter in your system, using virtual environment is adviced. In the cloned repository:

$ python3 -m venv .venv

Activate the repository:

(linux) $ source .venv/bin/activate

(windows, PowerShell) $ .venv/bin/activate.ps1

Install Sphinx:

(.venv) $ pip install sphinx

Building pretty-view

The Sphinx is configured to create documentation web page (HTML) and PDF document. To build it:

(.venv) $ sphinx-build -b html source build/html

The resulting HTML can be found in build/html folder.

Alternatively, you can use make or make.bat:

(.venv) $ make html

To create a PDF document, you need to had LaTeX installed on top of Sphinx. When LaTeX is ready, following command will generate PDF outpu in build/latex:

(.venv) $ make latexpdf