Documentation Guide

Overview

EzSnmp documentation is organized across multiple files and directories to provide comprehensive information for different audiences and use cases.

Documentation Structure

Repository Documentation

Main README (README.rst)

The main project README provides:

  • Project overview and introduction

  • Why EzSnmp was created

  • Links to documentation

  • How to support the project

  • License and copyright information

  • Acknowledgments

Directory READMEs

Each major directory contains its own README.rst:

  • cml_tests/README.rst - CML testing overview

  • cpp_tests/README.rst - C++ unit tests documentation

  • python_tests/README.rst - Python test suite with setup instructions

  • ezsnmp/README.rst - Source code structure and build process

  • images/README.rst - Image assets documentation

  • integration_tests/README.rst - Integration test scenarios

  • docker/*/README.rst - Docker container documentation for each platform

Sphinx Documentation

The Sphinx documentation (this site) provides:

Getting Started

  • Installation instructions for multiple platforms

  • Quick start examples

  • Session configuration examples

  • Exception handling guide

API Reference

  • Python class documentation

  • C++ class documentation (via Doxygen/Breathe)

  • SWIG interface documentation

Guides

Building Documentation

Doxygen Documentation

Doxygen generates C++ API documentation from source code comments.

Build doxygen documentation:

cd /path/to/ezsnmp
rm -rf doxygen_docs_build/
mkdir doxygen_docs_build
doxygen .doxygen

The XML output will be generated in doxygen_docs_build/doxygen/xml/.

Important: Doxygen must be run before building Sphinx documentation, as Sphinx uses the Breathe extension to integrate the doxygen XML files.

Sphinx Documentation

Sphinx builds the HTML documentation from reStructuredText (.rst) files.

Prerequisites:

cd sphinx_docs_build
pip install -r requirements.txt

Build process:

# 1. First build doxygen (see above)
cd /path/to/ezsnmp
mkdir doxygen_docs_build
doxygen .doxygen

# 2. Then build sphinx
cd sphinx_docs_build
mkdir -p source/_static source/_templates
make clean
make html

The HTML output will be in docs/html/.

Documentation Workflow

For Contributors

When contributing to EzSnmp:

  1. Update relevant README files if you add new directories or major features

  2. Add docstrings to Python code following existing style

  3. Add Doxygen comments to C++ code using standard Doxygen format

  4. Update .rst files if you change APIs or add major functionality

  5. Rebuild documentation locally to verify your changes

Adding New Documentation

To add new documentation pages:

  1. Create a new .rst file in sphinx_docs_build/source/

  2. Add appropriate reStructuredText content

  3. Include the file in an appropriate toctree (usually in modules.rst)

  4. Rebuild documentation to verify

Documentation Standards

reStructuredText Guidelines

  • Use descriptive section headers with proper underlining

  • Include code blocks with appropriate language tags

  • Use relative links for internal documentation

  • Add alt text to all images

  • Keep line length reasonable (80-100 characters)

Code Documentation

Python:

  • Use Google-style or NumPy-style docstrings

  • Document all public classes, methods, and functions

  • Include parameter types and return types

  • Provide usage examples where helpful

C++:

  • Use Doxygen comment style (/** ... */ or ///)

  • Document all public classes, methods, and functions

  • Use @param, @return, @throws tags

  • Include brief and detailed descriptions

Checking Documentation

Before committing documentation changes:

# Build doxygen
doxygen .doxygen

# Build sphinx
cd sphinx_docs_build
make clean
make html

# Check for warnings
# Sphinx will show warnings for:
# - Broken links
# - Missing files
# - Invalid syntax
# - Missing references

View the generated HTML in docs/html/index.html to verify:

  • All pages render correctly

  • Links work properly

  • Code examples display properly

  • Images appear correctly

  • Table of contents is accurate

Resources