Doc

This repository contains the Sphinx (https://sphinx-doc.org/) documentation for
all Bricks and Bricklets.

Requirements

• Python 3.9+
• Sphinx 7.0+

Setup

Clone the repository::

git clone https://github.com/Tinkerforge/doc
cd doc

Create and activate a virtual environment::

python3 -m venv sphinx-virtualenv
source sphinx-virtualenv/bin/activate

Install dependencies::

pip install -r requirements.txt

Install custom Pygments lexers::

pip install ./pygments-mathematica
pip install ./pygments-octave-fixed

Generating Documentation

The documentation is partly auto-generated. Clone the generators repository
and run the generation scripts::

git clone https://github.com/Tinkerforge/generators
cd generators/
python3 generate_all.py
python3 copy_all.py
cd ..

Note: Device examples are in their own repositories. To create the complete
documentation including all examples, all repositories from
https://github.com/Tinkerforge need to be cloned.

Building

Build HTML documentation for English::

cd en
source ../sphinx-virtualenv/bin/activate
sphinx-build -j auto -b html source build/html

Build HTML documentation for German::

cd de
source ../sphinx-virtualenv/bin/activate
sphinx-build -j auto -b html source build/html

Alternatively, use make html in the en or de directories.

Rebuilding

To rebuild with the latest changes, pull the doc and generators repositories
and re-run the generation scripts before building::

cd generators/
git pull
python3 generate_all.py
python3 copy_all.py
cd ../doc
git pull