Build and Install Documentation

Important

This guide assumes that the library as been built following the steps outlined in Build and Install on Ubuntu. Else, paths might need to be adjusted to align with the followed procedure.

EasyNMEA’s documentation is comprised of Doxygen and Sphinx HTML output. The process of building the documentation entails installation of additional tools for both the Doxygen and Sphinx documentations.

Environment Setup

To ease the development process, and to avoid version incompatibilities or clashes, this guide describes the process of building the documentation using Python3 Virtual Environments. Before setting up the environment, Doxygen needs to be installed. Install venv and Doxygen, and create a virtual environment and install the necessary tools with:

cd ~
sudo apt update && sudo apt install -y python3-venv doxygen plantuml
python3 -m venv easynmea_venv
source easynmea_venv/bin/activate
pip3 install -r ~/easynmea/docs/requirements.txt

Build

After setting up the environment, the documentation can be built with:

source ~/easynmea_venv/bin/activate
cd ~/easynmea/build
cmake .. -DBUILD_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=<user-specified-dir>
cmake --build .

Install

After building the documentation, it can be installed with:

source ~/easynmea_venv/bin/activate
cd ~/easynmea/build
cmake --build . --target install

Simulate Read The Docs Build

To simulate the process followed on the Read The Docs <https://readthedocs.org/> to build this documentation, run:

source ~/easynmea_venv/bin/activate
cd ~/easynmea
rm -rf build  # Just in case
READTHEDOCS=True sphinx-build \
    -b html \
    -D breathe_projects.easynmea=<abs_path_to_docs_repo>/build/docs/doxygen/xml \
    -d <abs_path_to_docs_repo>/build/docs/doctrees \
    docs <abs_path_to_docs_repo>/build/docs/sphinx/html