Building the Documentation¶

Libtropic documentation is built using the two following frameworks, each building a different part of the documentation:

MkDocs, used to generate the pages you are seeing right now,
Doxygen, used to generate the API Reference from the libtropic source code.

Normally, you should not need to build the documentation yourself - it is available on our GitHub Pages, where versions for the master branch and all releases are automatically built and released by our GitHub Actions. However, in the case of contributing to the documentation, it is handy to be able to build it locally and preview the new changes. Refer to the following sections for steps on how to do that.

Installation of the Dependencies¶

Important

Before proceeding, you need to have Python 3.x installed on your system.

To install MkDocs, do the following:

We recommend creating a Python Virtual Environment, for example with a name .docs-venv:
```
python3 -m venv .docs-venv
source .docs-venv/bin/activate
```

Update pip and install the needed pip packages using docs/requirements.txt:

pip install --upgrade pip
pip install -r docs/requirements.txt

After that, install Doxygen and Graphviz (used for the diagrams) - installation depends on your system, but we will use Ubuntu in this example:

sudo apt-get install doxygen graphviz

Building with Doxygen¶

First, the API Reference has to be built using Doxygen:

Switch to docs/doxygen/:
```
cd docs/doxygen/
```
Build:
```
doxygen Doxyfile.in
```

The API Reference should be now built in docs/doxygen/build/html/.

Note

These steps have to be done each time the contents of docs/doxygen/ change and you want to preview the changes.

Building with MkDocs¶

MkDocs has the ability to run a builtin development server on localhost, where the documentation is automatically deployed. To run it, switch to the root libtropic directory, where mkdocs.yml is located, and run:

mkdocs serve

In the terminal, you should see the address of the server. While holding CTRL, left-click the address to open it in your browser (or just manually copy it).

Warning

MkDocs does not rebuilt the Doxygen documentation automatically - to rebuild it, repeat the steps from section Building with Doxygen.

Tip

Each time you edit some files inside docs/, the server does not have to be stopped and run again - the server content will be automatically reloaded on each file save.

Versioned Documentation¶

When you build the documentation using the steps from the section Building with MkDocs, the version selector in the page header is not visible as it is on our GitHub Pages. That is because for the versioning, we use the mike plugin for MkDocs. This plugin maintains the gh-pages branch, from which the GitHub Pages are deployed.

Previewing the Versioned Documentation¶

The most common and safe use case is to locally preview the state of the documentation that is deployed to our GitHub Pages. Do the following steps to achieve that:

Make sure you have the latest version of the gh-pages branch from origin:
```
git fetch origin
git pull origin gh-pages
```
Do not git checkout gh-pages, because you will not be able to build the documentation there. Do git checkout with master, develop or any other branch based from one of these.
Run a builtin development server with the contents of gh-pages:
```
mike serve
```
In the terminal, you should see the address of the server. While holding CTRL, left-click the address to open it in your browser (or just manually copy it).

Editing the Versioned Documentation¶

Danger

Some of the following commands change the state of the local git repository, specifically the gh-pages branch, and possibly the origin remote!

If you need to locally deploy a new version and preview it, you have to modify the gh-pages branch. To do that, run:

mike deploy <version_name>

After running this, gh-pages branch will be created (if it does not already exist) and the generated documentation will be pushed to it.

Danger

If you add the --push flag, the gh-pages branch will be pushed to origin - we do not recommend doing that! This applies to most of the mike commands.

To see all existing versions, run:

mike list

Note

This command is safe - it does not change gh-pages branch.

To remove a specific version, run:

mike delete

There are more commands available - refer to the mike repository for more information.