Doc Implementation

This page explains how the documentation is implemented in the NTU Racing Team Zephyr Common and how to build it from the source.

Building the Documentation

Requirements

Note

If you are using the Docker image provided by the NTU Racing Team’s Zephyr workspace, the requirements are already installed and you can skip this section.

This documentation requires the following packages:

APT packages

doxygen=1.12.0
graphviz
make

Note

The version of doxygen is important as the configuration file is spciific to that version. Since currently the latest version of doxygen in ubuntu is 1.9.6, you may need to download it manually from Doxygen Download.

pip modules

breathe
sphinx
sphinx-rtd-theme

Building the Documentation

To build the documentation, run the following command:

# in <nturt_zephyr_common>/doc
make html

then the main documentation and API reference will be built in the _build/html and _build_doxygen/html directories respectively, which can be viewed in a browser by opening the index.html file.

Deploying to GitHub Pages with GitHub Actions

For ease of access, the main documentation you are reading right now is deployed to GitHub Pages at https://nturacingteam.github.io/nturt_zephyr_common, which is automated using GiHub Actions.

The GitHub Actions workflow is defined in .github/workflows/doc.yml. And it mainly uses Sphinx to GitHub Pages and GitHub Pages actions to build and deploy the documentation. The installation process is the same as described above, with the Doxygen installation copied from Zephyr.

Implementation Details

Main Documentation

The main documentation that you are reading right now is generated using Sphinx with Read the Docs theme. And API references generated by Doxygen are exported to the main documentation using Breathe.

API Reference

The API reference is generated using Doxygen with Doxygen Awesome theme.