Purpose: Doxygen automatically generates documentation from specially formatted code comments. This forms the foundation for most SCOREC software documentation. It is particularly useful for API documentation. See an example here.

Steps:

Install Doxygen
- Install doxygen (instructions) or use an existing installation.
- As of November 2025, on SCOREC systems the following commands will give you access to a Doxygen install:
```
module use /opt/scorec/spack/rhel9/v0201_4/lmod/linux-rhel9-x86_64/Core/
module load gcc/12.3.0-iil3lno doxygen/1.9.6-5ppxahb
```
Add Documentation Comments
- Use Doxygen comment syntax in your code. A simple example is like:

     /**
       * \brief Brief description of the function
       * \param paramName Description of parameter
       * \return Description of return value
       */

Detailed syntax can be found in their documentation

Create Configuration File
- Generate a default configuration file with doxygen -g Doxyfile. Alternatively, you can generate it from a template file called doxyfile.in. See example here from PUMI.
- Customize settings (project name, input directories, output format).
Generate Documentation
- Run: doxygen Doxyfile
- Output will be in the specified directory (e.g. html/ or latex/)

2. Enhancing with Sphinx (Optional)

While Doxygen handles API documentation well, Sphinx provides a more modern, extensible framework for comprehensive project documentation including tutorials, guides, and custom pages. Though Sphinx is primarily a Python tool, it can be integrated with Doxygen using Breathe. Example documentation from redev can be found here

Steps:

Set Up Python Environment

#/bin/bash
python3 -m venv pyEnv
source pyEnv/bin/activate
pip install -r requirements.txt

An example requirements.txt environment from redev is:

Sphinx==8.2.3
sphinx-rtd-theme==3.0.2
sphinx-sitemap==2.6.0
breathe==4.35.0

Other sphinx add-ons can be added if needed.

Initialize Sphinx

Initialization helps you build the documentation structure quickly during initial setup. It is not needed after the initial configuration.

   sphinx-quickstart docs

Configure Sphinx
- Edit docs/conf.py to include Breathe extension
- Point Breathe to your Doxygen XML output
- Customize theme and settings
- Example can be found here.
Create Content
- Write .rst files for guides, tutorials, and overview pages. Guide on .rst files can be found here.
- Use Breathe directives to include Doxygen-generated API docs. An example from redev can be found here.
Build Documentation

   # Generate Doxygen XML first
   doxygen Doxyfile
   
   # Build Sphinx documentation
   make html

3. Hosting Your Documentation

GitHub Pages (Recommended for Quick Setup)

GitHub Pages offers free, straightforward hosting directly from your repository.

Option A: Deploy via Branch

Create a gh-pages branch
Push your generated HTML to this branch
Enable GitHub Pages in repository settings (source: gh-pages branch)
Documentation automatically updates on each push
Consider using a cron job instead of manual push
Example script available from redev

Option B: Deploy via GitHub Actions

Create a workflow file (e.g. .github/workflows/docs.yml)
Configure automated builds and deployments on push/merge
Example workflow available in PUMI

Read the Docs (For Advanced Needs)

When to use: ReadtheDocs is ideal for projects requiring complex use case like automatic versioning or page analysis. An detailed comparison with GitHub Pages can be found here.

Setup:

Sign up at readthedocs.org
Connect your repository
Add a .readthedocs.yaml configuration file. Example can be found here.
Documentation builds automatically on commits

4 - Methods

Background Materials on Methodologies

4.1 - Code Coupling

Background on Code Coupling Techniques

4.2 - Multiscale Modeling

Background on Multiscale Modeling Techniques

4.3 - Particle in Cell Methods

Background Material on Particle in Cell Methods