Documentation Guide¶

SeQuant uses a combination of Doxygen, Sphinx and Breathe to build documentation. 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. The documentation is generated using Doxygen and Sphinx .

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, Breathe, Exhale, and others. Now 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.

mkdir build
cd build
cmake -DSEQUANT_BUILD_DOCS=ON ..
cmake --build . --target doc-sequant

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)

Building Documentation¶

To build the documentation, run the following commands:

cmake -B build
cmake --build build --target doc-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.

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

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

Links¶

Create hyperlinks:

`Link text <https://example.com>`_

Refer to another section in the documentation:

See the :ref:`section-name` for more details.

Refer to another file in the documentation:

See the :doc:`user/installation` for installation instructions.

Make sure to use the correct relative path to the file you are linking to.

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) {
    if constexpr (std::is_arithmetic_v<T>) {
        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.