Skip to content

Building the Documentation

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

  1. MkDocs, used to generate the pages you are seeing now,
  2. Doxygen, used to generate the API Reference from the Libtropic source code.

Normally, you do not need to build the documentation yourself; it is available on our GitHub Pages, where versions for all releases are automatically built and released by our GitHub Actions. However, when contributing to the documentation, it is useful to build it locally and preview changes. See the following sections for instructions.

Install the Dependencies

Installing dependencies

First, install MkDocs dependencies:

  1. Install Python (version 3.8 or later)
    • You can also use your distribution's package manager:
      • Fedora: sudo dnf install python3
      • Debian/Ubuntu: sudo apt update && sudo apt install python3
  2. We recommend creating a Python virtual environment, for example named .docs-venv: 
    python3 -m venv .docs-venv
source .docs-venv/bin/activate
  3. Update pip and install the required packages from docs/requirements.txt: 
    pip install --upgrade pip
pip install -r docs/requirements.txt

After that, install Doxygen and Graphviz (used for diagrams):

  • Fedora: sudo dnf install doxygen graphviz
  • Debian/Ubuntu: sudo apt update && sudo apt install doxygen graphviz

TBA

TBA

Build Doxygen Documentation

First, build the API Reference using Doxygen:

Building Doxygen Documentation

  1. Switch to docs/doxygen/: 
    cd docs/doxygen/
  2. Build: 
    doxygen Doxyfile.in

TBA

TBA

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

Warning

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

Build MkDocs Documentation

MkDocs can run a built-in development server on localhost that serves the documentation. To run it, switch to the root Libtropic directory (where mkdocs.yml is located) and run:

Building MkDocs Documentation

mkdocs serve --livereload
In the terminal, you should see the address of the server. To open it in your browser, press Ctrl + Left Click or copy the address manually.

TBA

TBA

Warning

MkDocs does not rebuild the Doxygen documentation automatically; to rebuild it, repeat the steps from section Build Doxygen Documentation.

Tip

You do not need to stop and restart the server each time you edit files inside docs/; the server reloads content automatically on each save.

Versioned Documentation

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

Preview 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:

Previewing the Versioned Documentation

  1. Make sure you have the latest version of the gh-pages branch from origin: 
    git fetch origin gh-pages:gh-pages
    Do not git checkout gh-pages, because you will not be able to build the documentation there. Instead, git checkout master, develop, or any other branch based on one of these.
  2. Run a built-in development server with the contents of gh-pages: 
    mike serve

In the terminal, you should see the address of the server. To open it in your browser, press Ctrl + Left Click or just manually copy it.

TBA

TBA

Edit 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 deploy a new version locally and preview it, you must modify the gh-pages branch:

Locally Deploying a New Version

mike deploy <version_name>
After running this, the 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 mike commands.

TBA

TBA

To see all existing versions, do:

Seeing Existing Versions

mike list

Info

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

TBA

TBA

To remove a specific version, do:

Deleting Existing Version

mike delete <version_name>

TBA

TBA

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