This project uses a combination of tools to generate comprehensive documentation:

• Doxygen: Parses the C++ source code comments (/** ... */) to automatically generate a detailed API reference (classes, functions, variables, etc.). It outputs this information as XML files.
• Sphinx: The main documentation generator. It takes narrative content written in reStructuredText (.rst) or Markdown (.md) files and builds the final documentation website (HTML), PDFs, or other formats.
• Breathe: A Sphinx extension that acts as a bridge. It reads the XML files generated by Doxygen and allows embedding the C++ API documentation seamlessly within the Sphinx-generated pages, creating a single, unified documentation site.
• ReadTheDocs: The platform used for automatically building, hosting, and versioning the official online documentation website from our GitHub repository.
• (Theme) sphinx-rtd-theme: The visual theme used for the Sphinx documentation, providing the look and feel consistent with many other open-source projects.

This is useful for previewing changes before committing or pushing them.

Prerequisites:

• Python: Version 3.10 or higher. pip and venv should be included.
• Doxygen: The Doxygen executable must be installed and available in your system's PATH (sudo apt install doxygen or brew install doxygen)

Steps:

1. Set up Python Virtual Environment:

   Navigate to the docs directory and create/activate a virtual environment to isolate dependencies.

   cd docs
   python -m venv .venv
   source .venv/bin/activate

   You should see (.venv) prepended to your shell prompt.

2. Install Python Dependencies:

   Install Sphinx, Breathe, the theme, and other necessary Python packages.

   pip install -r source/requirements.txt

3. Generate Doxygen XML Output:

   Run Doxygen to parse the C++ source code and generate the XML files that Breathe needs. Run this from the repository root directory.

   # Make sure you are in the ROOT directory of the repository
   # If you are inside 'docs', cd ..
   doxygen docs/doxygen/Doxyfile

4. Build the Documentation with Sphinx:

   Now, run the Sphinx build process using the Makefile provided by Sphinx. Make sure you are in the docs directory (where the Makefile resides).

   # cd docs
   
   # Optional: Clean previous builds
   make clean
   
   # Build the HTML documentation
   make html

   The generated HTML files will be in the build/html directory. Check docs/build/html/index.html

Optional

• Graphviz (Optional but Recommended for devs): Doxygen uses Graphviz (specifically the dot tool) to generate diagrams (like call graphs, inheritance graphs). If you want these diagrams, install Graphviz (sudo apt install graphviz or brew install graphviz).

• Doxygen also can generate HTML own documentation, where you can see the inheritance graphs, list os classes, functions, variables, etc

  Open the generated HTML documentation in your web browser.

  # Path is relative to the 'docs' directory
  open docs/doxygen/html/index.html
  

Note: This opens the HTML documentation generated directly by Doxygen, which can be useful for debugging or viewing diagrams. It is separate from the integrated documentation built via make html.

• Deployment needs to be configured via the GUI of readthedocs
• The file .readthedocs.yaml contains the necessary configuration

• https://docs.readthedocs.com/platform/stable/tutorial/index.html
• https://www.youtube.com/watch?v=pnnKzkNTo4w
• https://www.youtube.com/watch?v=PO4Zd-6a6fA