Documentation Guide

Overview

EzSnmp Data Logger mirrors the exact documentation architecture used across ezsnmp, purpleair_data_logger, and purpleair_api:

  1. Doxygen extracts XML API metadata from C++17 headers in include/ezsnmp_data_logger/ and src/.

  2. Sphinx + Breathe + Furo builds the main HTML documentation from sphinx_docs_build/source/ into docs/html/.

  3. Version-Selector Landing Page builds sphinx_docs_build/landing/source/index.rst into docs/index.html, linking Latest Alpha/Beta Version (./html/index.html) alongside historical release snapshots (./html_vX.Y.Z/index.html).

Building Documentation Locally

1. Generate Doxygen XML

Doxygen must run before Sphinx so Breathe can read doxygen_docs_build/doxygen/xml/:

cd /path/to/ezsnmp_data_logger
rm -rf doxygen_docs_build
mkdir -p doxygen_docs_build
doxygen .doxygen

2. Build Main Sphinx Documentation

Install documentation dependencies and build with SPHINXOPTS="-W" (warnings treated as errors):

python3 -m pip install -r sphinx_docs_build/requirements.txt
python3 setup.py build_ext --inplace
cd sphinx_docs_build
mkdir -p source/_static source/_templates
make clean
make html SPHINXOPTS="-W"

The generated site is written to docs/html/index.html.

3. Build Version-Selector Landing Page

cd sphinx_docs_build/landing
mkdir -p source/_static source/_templates
make html SPHINXOPTS="-W"

The top-level landing page is written to docs/index.html.

Note

Current build outputs (docs/html/, docs/_static/, docs/doctrees/, doxygen_docs_build/) are ignored by .gitignore and deployed automatically to GitHub Pages by .github/workflows/sphinx_build.yml. Versioned release folders (docs/html_v*) are preserved on main when tags are published.

Documentation Standards

  • Python Docstrings: Use Sphinx/reStructuredText field lists (:param:, :return:) on public classes and functions.

  • C++17 Comments: Use Doxygen /** ... */ blocks with @brief, @param, @return, and @throws tags on all public declarations in include/ezsnmp_data_logger/.

  • Software Requirements: Maintain [PREFIX-nn] + Shall requirements in Software Requirements.