generate-docs

name	generate-docs
description	Build documentation from code comments and LaTeX sources

Generate Docs

This skill handles documentation generation for FLEKS.

Documentation Locations

Type	Location
Algorithm documentation	docs/Algorithm.tex
Coding standards	docs/Coding_standards.md
Parameter documentation	PARAM.XML
User source templates	userfiles/*Source.h and Config.pl -u
Project overview (agent)	AGENT.md (root and subdirectories)

LaTeX Documentation

Build Algorithm PDF

cd docs
pdflatex Algorithm.tex

For full build with references:

cd docs
pdflatex Algorithm.tex
pdflatex Algorithm.tex  # Run twice for references

View Generated PDF

open docs/Algorithm.pdf  # macOS

Algorithm Document Contents

The Algorithm.tex covers:

• Unit conversion — CGS/SI normalization, mass/length/velocity/charge units
• Boris particle mover — Standard and relativistic versions
• Pressure tensor — Calculating total pressure from sub-groups

Code Documentation with Doxygen

If you want to add Doxygen-style documentation:

1. Install Doxygen

brew install doxygen  # macOS

2. Create Doxyfile

# Run from FLEKS project root
doxygen -g

3. Configure Doxyfile

Key settings to modify:

PROJECT_NAME = "FLEKS"
INPUT = include src
FILE_PATTERNS = *.h *.cpp
EXTRACT_ALL = YES
GENERATE_LATEX = NO

4. Generate Documentation

doxygen Doxyfile

Output will be in html/index.html.

Doxygen Comment Style

For Classes

/**
 * @brief A brief description of the class.
 *
 * A more detailed description of what this class does,
 * its purpose, and usage patterns.
 */
class MyClass {

For Functions

/**
 * @brief Brief description of the function.
 *
 * @param param1 Description of first parameter
 * @param param2 Description of second parameter
 * @return Description of return value
 *
 * @note Any important notes about usage
 * @warning Any warnings about side effects
 */
int my_function(int param1, double param2);

For Member Variables

class MyClass {
private:
  int count_;  ///< Number of items processed
  double tolerance_;  ///< Convergence tolerance for solver
};

PARAM.XML Documentation

The PARAM.XML file documents all input parameter commands. It uses SWMF's XML schema with <command>, <parameter>, <for>, and inline description text. Example structure:

<command name="TIMESTEPPING"
     alias="TIMESTEPPING_FLEKS0,TIMESTEPPING_FLEKS1"
     multiple="T">
  <parameter name="useFixedDt" type="logical" default="F"/>
  <parameter name="dt" type="real" if="$useFixedDt"/>
  <parameter name="cfl" type="real" default="0.2" if="not $useFixedDt"/>

#TIMESTEPPING
F                  useFixedDt
0.1                cfl (if useFixedDt is false)

Setting the CFL or fixed time step. The typical CFL number is 0.1~0.4.
</command>

When adding a new parameter command:

1. Add the <command> block to PARAM.XML
2. Implement parsing in the corresponding read_param() method (typically Domain.cpp or Pic.cpp)
3. Add the member variable to the appropriate class header

For user source behavior, keep #SOURCE in PARAM.XML aligned with Domain.cpp and the selection workflow in Config.pl -u. Add reusable source implementations under userfiles/*Source.h; include/UserSource.h is the selected copy generated by Config.pl.

AGENT.md Files

The project maintains AGENT.md files in key directories:

File	Purpose
AGENT.md	Root project overview, architecture, build system
include/AGENT.md	Header file catalog and conventions
src/AGENT.md	Implementation file guide and Makefile details
srcInterface/AGENT.md	SWMF coupling layer documentation

Update these when adding new classes, files, or changing architecture.

Documentation Checklist

• All public classes have brief descriptions
• All public functions have parameter documentation
• Complex algorithms have detailed comments
• PARAM.XML is up-to-date with new parameters
• Algorithm.tex reflects current implementation
• AGENT.md files updated for new files/classes