API documentation website

This repo exists to build the API documentation website.

Building

1. Install Doxygen
2. Run pipenv install to install Sphinx and its extensions.
3. Run make build

Deploying

Deployment is to the pages branch of this repository, as we're hosting on Codeberg pages. Run make deploy to get this done.

Details

Each of interpeer's project repos contains its own documentation. As we'd like to provide more than just automatically generated API docs, we're using Sphinx to maintain this. However, that system does not deal well with C/C++ source files.

Breathe is an extension to Sphinx that runs Doxygen to generate XML output, and provides Sphinx directives for adding the Doxygen data to the Sphinx documentation.

In each project, we're looking for a Makefile in docs/api to detect whether it has Sphinx documentation. If found, the documentation is built, and copied to a project subdirectory in output.

The contents of the output folder are then pushed to the pages branch for publication.

As an additional wrinkle, we're using the interpeer theme to generate CSS. This is not necessary for building documentation, but it helps style the documentation website a little more consistently with the main website.