One Good Tutorial provides a great framework and checklist for creating effective minimal documentation. It also recommends tools and best practices for writing clear, concise documentation.

Setting Up Documentation for SCOREC Projects

This guide walks you through creating documentation for your SCOREC project.

Basic Steps

Add comprehensive comments to your class, functions …
Choose your hosting platform based on project complexity
Consider automating documentation builds in your CI/CD pipeline

1. Setting Up Doxygen

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

Reference Material

1 - Applications

Degas2

.web Files

2 - C++ Reference

Stack vs. Heap

3 - Documentation

Minimum Documentation Standard