Documentation Guidelines

GPUmonty is a public, open-source project. To ensure the codebase remains accessible and maintainable for the scientific community, we provide this centralized documentation as a guide for both users and contributors.

The documentation and this site is built using a hybrid pipeline: Doxygen is used to parse the source code and extract structural metadata into XML format, while Sphinx serves as the primary engine to render this information into a web interface. Using the Breathe extension, we ensure that the API reference is always in sync with the latest version of the code. Prerequisites

File-Based Organization and Commenting

To maintain a clear structure, the documentation is organized by source file. Each header file (.h) in the repository corresponds to a tab of the documentation. This allows users to browse functionality based on the specific file they are investigating.

Function Documentation

All function-level documentation must be associated directly with the function declaration in the header files. By keeping the documentation in the headers rather than the source (.cu) files, we hope to keep the function definition cleaner.

When adding or updating functions, use the Javadoc-style comment block immediately above the declaration:

/**
 * @brief A concise one-line description of the function.
 * * Detailed explanation of the physical model or numerical method used.
 * * @param parameter_name Description of the input.
 * @return Description of the return value.
 */
__host__ __device__ double example_function(double parameter_name);

Guidelines:

Consistency: Ensure the @brief tag is present; it is used to generate the summary tables in the sidebar.
Math: Use LaTeX syntax (\f$ ... \f$) for physical variables (e.g., \f$ \Theta_e \f$) to ensure they render correctly on the site.
Scope: Documentation should live in the header files.

Update Workflow and Repository Structure

The GPUmonty documentation synchronizes with the latest updates from the GitHub repository. When changes are pushed to the main branch, the documentation pipeline processes the source code to ensure the web portal reflects the current state of the project.

Documentation Directories Organization

The documentation environment is organized into three primary folders:

Directory	Purpose
`/`	Doxyfile: Contains the Doxyfile configuration used by Doxygen to parse the source code.
`docs/`	Source Directory: Contains the Sphinx configuration (`conf.py`), and all `.rst` source files.
`html/`	Web Output: Stores the generated HTML files, CSS, and JavaScript that constitute the public website.
`latex/`	Print Output: Contains the LaTeX source files used to generate the PDF version of the manual.

Website Navigation and Tabs

The structure of the website is determined by the organization of .rst files within the docs/ folder:

Primary Tabs: Every .rst file located directly in the root of the docs/ directory (such as quickstart.rst or guidelines.rst) corresponds to a main navigation tab or section visible from the homepage.
API Pages: The technical documentation for each code module is organized within the docs/api/ subdirectory. For example, the documentation for weight calculations is defined in docs/api/weights.rst.

How it Works

Extraction: Doxygen scans the header files and generates XML metadata representing the code structure. Translation: The Breathe extension acts as a bridge, allowing Sphinx to read that XML and insert it into the .rst files found in docs/api/. Rendering: Sphinx converts the .rst files into the final HTML layout.

Because the documentation is built directly from the source code, any update to a comment block in a header file (.h) will automatically update the corresponding page in the API section upon the next site build.

Local Testing and Building

Since any changes to the documentation affect the live website, we encourage local testing before committing and pushing to the repository.

Prerequisites

You must have Doxygen and Sphinx installed on your system.

1. Install Doxygen (Ubuntu/Debian):

sudo apt update
sudo apt install doxygen

2. Install Sphinx and Extensions:

pip install sphinx sphinx-autobuild breathe exhale sphinx_rtd_theme

Testing Workflow

Follow these steps to preview your changes locally:

Update Doxyfile/XML: If you have modified the Doxyfile or changed comments in the code headers, run Doxygen to update the XML metadata:
```
doxygen Doxyfile
```
Launch Auto-build: Open a second terminal and run the following command to keep the site updated automatically as you edit .rst files:
```
sphinx-autobuild docs docs/_build/html
```
Preview Changes: Open your browser and navigate to:

http://127.0.0.1:8000
Clean Build: Sphinx caches files to speed up building. If you want to force a total rebuild to ensure everything is fresh, delete the build directory:
```
rm -rf docs/_build
```

Because the documentation is built directly from the source code, any update to a comment block in a header file (.h) will automatically update the corresponding page in the API section upon the next build.