=============================
How to Use This Documentation
=============================

This documentation is generated using Sphinx. While Sphinx is powerful, there are some pitfalls and also some conventions we will establish. It uses reStructuredText (reST) as its markup language.

We will use the NumPy docstring style and this should be the only one enabled.

Here is an example of a properly formatted docstring:

.. code-block:: python

    def func(arg1, arg2):
        """Summary line.

        Extended description of function.

        Parameters
        ----------
        arg1 : int
            Description of arg1
        arg2 : str
            Description of arg2

        Returns
        -------
        bool
            Description of return value

        """
        return True

Refer to the `NumPy Guide <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_ for more details.

Also folow our `style guide <caite-main-app/caite-app-dev/style-guide.rst>`_ for more information on how to write good code and documentation.


How to build the documentation
------------------------------

Please install the requirements  from  ``requirements.txt``  in a env called :  ``.docs-venv/`` and then activate it.
To build the documentation, navigate to the ``docs`` directory and run (assuming you have Linux and a bash shell):

.. code-block:: bash

    make html

This will generate the HTML documentation in the ``_build/html`` directory.
You can view it in your web browser, e.g. by using the VS Code extension.
Make sure to have Sphinx and the necessary extensions installed in your Python environment.

There is a VS Code extension `that can help you generate docstrings <https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring>`_.

If you want to generate some nice diagrams, you can uses Mermaid. You can use the `Mermaid Live Editor <https://mermaid.live/>`_ to create your diagrams and then include them in your documentation using the appropriate syntax.