Documentation Guide

SeQuant uses Doxygen and Sphinx to build documentation. The API documentation can be generated in two modes:

  1. Standalone Doxygen (default): Fast generation using modern Doxygen Awesome CSS theme

  2. Breathe/Exhale integration: Slower but integrates API docs directly into Sphinx (enable with -DSEQUANT_BUILD_DOCS_API_BREATHEEXHALE=ON)

For building the documentation locally, configure CMake with -DSEQUANT_BUILD_DOCS=ON.

The doc directory contains the documentation for SeQuant, including user guides, API references, and advanced internal documentation.

Dependencies

Building the documentation requires several Python packages. You can install them using pip. The required packages are listed in the requirements.txt file in the doc/.sphinx directory. You can install them using the following command:

pip install -r doc/.sphinx/requirements.txt

This will install the required packages, including Sphinx and optionally Breathe/Exhale (only needed if SEQUANT_BUILD_DOCS_API_BREATHEEXHALE=ON).

Directory Structure

  • CMakeLists.txt - Main build file for all documentation

  • .doxygen/ - Doxygen configuration for API reference documentation

    • Doxyfile.in - Doxygen configuration template

  • .sphinx/ - Sphinx documentation source files

    • conf.py.in - Sphinx configuration template

    • index.rst - Main index file for documentation

    • requirements.txt - Python dependencies for building docs

    • user/ - User-facing documentation: basic usage guides, installation instructions, etc.

    • developer/ - Advanced developer documentation

    • api/ - API documentation (generated by Exhale/Breathe when SEQUANT_BUILD_DOCS_API_BREATHEEXHALE=ON)

Building Documentation

After all dependencies are installed, you can build the documentation using CMake. The documentation will be generated in doc/html under your build directory. You can open the index.html file in your web browser to view the documentation.

cmake -B build -S . -DSEQUANT_BUILD_DOCS=ON ..
cmake --build . --target html-sequant

This will generate both Doxygen and Sphinx documentation. The output directories are:

  • Doxygen HTML: build/doc/.doxygen/html/

  • Sphinx HTML: build/doc/html/

How It Works

The documentation setup works through a chain of tools that transform code comments into organized web pages.

Default Mode (Standalone Doxygen):

  • Doxygen: Extracts comments from C++ source and generates standalone HTML using Doxygen Awesome CSS theme

  • Sphinx: Builds user/developer documentation and links to the standalone Doxygen HTML

Breathe/Exhale Mode (when SEQUANT_BUILD_DOCS_API_BREATHEEXHALE=ON ):

  • Doxygen: Extracts comments and documentation from C++ source files and creates XML files

  • Sphinx: The main documentation builder that creates HTML pages

  • Breathe: Connects Doxygen and Sphinx, allowing Sphinx to use the XML files generated by Doxygen

  • Exhale: Automatically builds pages for all the classes and functions in the codebase and integrates them into Sphinx

Adding New Documentation

All user-facing documentation should be added to the .sphinx/user/ directory. Internal documentation can be added to the .sphinx/developer/ directory.

New documentation files should be written in reStructuredText format and included in the appropriate toctree section of index.rst files. For a quick reference on reStructuredText syntax, see this sheet.

Examples of reStructuredText Syntax

Here are some common reStructuredText (reST) syntax examples:

Headings

Use equal signs, dashes, or other characters to create headings:

Heading Level 1
===============

Heading Level 2
---------------

Heading Level 3
~~~~~~~~~~~~~~~

You can also use other characters for different levels:

Heading Level 4
^^^^^^^^^^^^^^^

Heading Level 5
^^^^^^^^^^^^^^^

Lists

Create bullet and numbered lists:

- Bullet list item 1
- Bullet list item 2

1. Numbered list item 1
2. Numbered list item 2

You can also create nested lists:

- Main item
  - Subitem 1
  - Subitem 2
1. First item
2. Second item

Code Blocks

Include code blocks with syntax highlighting. Use the .. code-block:: <language> directive:

Python:

def example_function():
    print("Hello, World!")

C++:

#include <iostream>

int main() {
    std::cout << "Hello, C++!" << std::endl;
    return 0;
}

Inline Code

For inline code snippets, use backticks:

Use the ``get_data()`` function to retrieve the values.

API Documentation

API documentation is automatically generated from the source code using Doxygen and Exhale. Below is a minimal example of how to document a function using Doxygen-style comments:

/**
 * @brief Adds two values.
 *
 * @tparam T Type of the input values.
 * @param a The first parameter.
 * @param b The second parameter.
 * @return The result of the operation.
 */
template <typename T>
T add(T a, T b) {
  return a + b;
}

Ensure that all functions, classes, and methods in the C++ source code are properly documented using this format for accurate API documentation generation.