Generate documentation

GISNav uses a two-stage process to generate its documentation. Sphinx is used to first build Markdown from the reStructuredText docstrings in the Python source code, and then VitePress is used to create the final static documentation from the Markdown files.

Prerequisites

Node.js

Install Node v18+ on your system by following the official instructions.

Install GISNav

The prerequisites depend on whether you are running a local installation or using a Docker container.

Local

These instructions assume you have installed GISNav locally.

Development dependencies required

Remember to also install the development dependencies as instructed in the Python dependencies section.

Docker

Follow the Docker Compose deployment instructions to build the gisnav Docker image and to create the container.

Make docs

The documentation is built in a two-stage process where first the reST Python docstrings are converted into Markdown files using Sphinx, after which they are built into the final static documentation page using VitePress.

The Makefile docs target implements this recipe:

Local

cd ~/colcon_ws/src/gisnav
make docs

Docker

cd ~/colcon_ws/src/gisnav/docker
docker compose -p gisnav run gisnav make docs

The static HTML documentation will appear in the below folder:

~/colcon_ws/src/gisnav/docs/vitepress/docs/.vitepress/dist

Serve VitePress documentation

cd ~/colcon_ws/src/gisnav/docs/vitepress
npm run docs:dev