Documentation#

The documentation is built using Sphinx.

Add new static pages#

The static pages you can add are written in reStructuredText (.rst). You need to put them in the docs/source folder with a .rst extension.

For example, this page looks like this in reStructuredText :

Documentation
=============

The documentation is built using Sphinx_.

.. _Sphinx: https://www.sphinx-doc.org/en/master/

Add new static pages
--------------------

The static pages you can add are written in reStructuredText (.rst).
You need to put them in the ``docs/source`` folder with a ``.rst`` extension.

For example, this page looks like this in reStructuredText :

.. code-block:: text

    Documentation
    =============

    The documentation is built using Sphinx_.

    .. _Sphinx: https://www.sphinx-doc.org/en/master/

    Add new static pages
    --------------------

    The static pages you can add are written in reStructuredText (.rst).
    You need to put them in the ``docs/source`` folder with a ``.rst`` extension.

    For example, this page looks like this in reStructuredText :

    .. code-block:: text

        # nothing there, otherwise we have an infinite recursion

    .. seealso::

    For further details about the *reStructuredText* syntax, see the Sphinx docs_

    .. _docs: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer

.. seealso::

For further details about the *reStructuredText* syntax, see the Sphinx docs_

.. _docs: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer

Add docs to the code#

The documented code can be interpreted in HTML to give nice API docs, for examples, see pygeodes.

To properly document a function, you need to respect the numpydoc convention, let’s see an example function :

    def file_exists(filepath: str, raise_exception: bool = True) -> bool:
"""This checks if the file exists, and, in function of a boolean parameter, raises an exception if it doesn't

Parameters
----------
filepath : str
    the filepath to check the existence of
raise_exception : bool, optional
    whether to raise an exception, by default True

Returns
-------
bool
    whether the file exists

Raises
------
FileNotFoundError
    error raised if the file doesn't exist

See Also
--------
similar_filenames : to find the most similar filenames to a filename

Examples
--------

.. code-block:: python

    name = "file.txt"
    exists = file_exists(name)

"""
filepath = os.path.abspath(filepath)
exists = os.path.exists(filepath)
if exists:
    return True
else:
    if raise_exception:
        raise FileNotFoundError(f"The file {filepath} doesn't exist")
    else:
        return False

To see the result given in HTML, please see pygeodes.utils.io.file_exists().

When you write a new function/class, just add your docs using the numpydoc syntax. When using make build_docs command (see Makefile), changes will be reflected in the HTML docs.

Configuration#

Sphinx can be configured using the docs/source/conf.py file. At the end of this file, we define variables that can used everywhere in the .rst files in the docs.