.. _documentation-guide:

Documentation Guide
====================

SeQuant uses a combination of `Doxygen <https://www.doxygen.nl/>`_, `Sphinx <https://www.sphinx-doc.org/en/master/>`_ and
`Breathe <https://breathe.readthedocs.io/en/latest/>`_ 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.

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:

.. code-block:: bash

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

This will install the required packages, including Sphinx, Breathe, Exhale, and others.

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
----------------------

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.

.. code-block:: bash

    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.

* **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 <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`_.

Examples of reStructuredText Syntax
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here are some common reStructuredText (reST) syntax examples:

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

.. code-block:: rst

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

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

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

You can also use other characters for different levels:

.. code-block:: rst

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

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

Lists
^^^^^
Create bullet and numbered lists:

.. code-block:: rst

    - Bullet list item 1
    - Bullet list item 2

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

You can also create nested lists:

.. code-block:: rst

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

Links
^^^^^
Create hyperlinks:

.. code-block:: rst

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

Refer to another section in the documentation:

.. code-block:: rst

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

Refer to another file in the documentation:

.. code-block:: rst

    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:

.. code-block:: python

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


C++:

.. code-block:: cpp

    #include <iostream>

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


Inline Code
^^^^^^^^^^^

For inline code snippets, use backticks:

.. code-block:: rst

    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:

.. code-block:: cpp

    /**
     * @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.