Documentation Setup Guide#

This README provides instructions for setting up and building the documentation for the FSI-Data-Shelter project using Sphinx.

Table of Contents#

Prerequisites
Installation
Configuring Sphinx
Documenting Your Code
Adding Documentation Files (.rst)
Building the Documentation
Iterating and Updating

Prerequisites#

Python: Ensure you have Python 3 installed on your system.
pip: Python package installer (should come with Python).
pandoc: A universal document converter used by nbsphinx (download the .msi) Note: Using conda-forge may work as an avenue to install pandoc:
```
conda install -c conda-forge pandoc
```

Installation#

Navigate to the project’s root directory in your terminal or command prompt.

Install Sphinx and the necessary themes/extensions:

pip install sphinx pydata-sphinx-theme myst-parser sphinx-copybutton nbsphinx

Configuring Sphinx#

The main configuration file for Sphinx is source/conf.py. Here are some key settings to be aware of:

html_theme: This should be set to 'pydata_sphinx_theme' to use the recommended theme.

extensions: Ensure the following extensions are included:

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.napoleon',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode',
'sphinx.ext.doctest',
'sphinx_copybutton',
'myst_parser',
'nbsphinx',
'pydata_sphinx_theme',

] **NOTE: `sphinx.ext.autodoc` will import modules in order to document them, meaning code not guarded by** python if name == ‘main’: ``` will be executed!

Documenting Your Code#

Sphinx primarily uses docstrings within your Python code to generate documentation. Follow these guidelines:

Use a consistent docstring style: NumPy or Google style are widely used and well-supported by the sphinx.ext.napoleon extension.
Document all modules, classes, functions, and methods: Explain their purpose, arguments, return values, and any exceptions they might raise.
Include examples in your docstrings to illustrate how to use the code. These examples can also be run as tests if you have the sphinx.ext.doctest extension enabled.

Example Python Function with Docstring:

def example_function(input_value: int) -> str:
    """A brief summary of the function.

    A more detailed explanation of what the function does.

    .. todo:: Refactor this function for better performance.

    Args:
        input_value (int): Description of the input value.

    Returns:
        str: Description of the return value.

    Example:
        >>> example_function(5)
        'Result based on 5'
    """
    return f"Result based on {input_value}"

Note: The .. todo:: directive is Sphinx-specific, as napoleon does not recognize any TODO: headers within Google-style docstrings

For more details, please see the Google documentation for more information.

Adding Documentation Files (.rst)#

Sphinx documentation is written in reStructuredText (.rst) format. Here’s how to create and add these files:

For API documentation (documenting Python code):#

We use an automated script to generate .rst files for Python modules. This script is automatically executed during the Sphinx build process.

Ensure the project root is in your PYTHONPATH (if running Sphinx manually):
```
export PYTHONPATH=$PYTHONPATH:.
```
The build process scans the project and automatically places .rst files in the appropriate subdirectories within source/ (e.g., source/utils/, source/reference/).
Verify the generated files in the source/ directory after the build.

For manual documentation:#

Create new .rst files using a plain text editor (e.g., concepts/my_concept.rst, tutorials/my_tutorial.rst).
Use reStructuredText syntax to structure your documentation. Refer to the reStructuredText Primer for details.

Linking Files:#

Link your .rst files in the toctree directive within your main source/index.rst file. This creates the navigation structure of your documentation.

.. toctree::
   :maxdepth: 2
   :caption: API Reference:
   :glob:

   api/*
   utils/*
   reference/*

:glob: allows us to use wildcard characters

NOTE: Sphinx is compatible with markdown files as well. If you have static documentation that does not depend on code, you may put it into a .md file and include it in the appropriate documentation directories.

Building the Documentation#

Navigate to the project’s root directory in your terminal.
Run the Sphinx build command:
```
sphinx-build -M html source build
```
The generated HTML documentation will be located in the build/html subdirectory. Open the build/html/index.html file in your web browser to view it.

Iterating and Updating#

After making changes to your docstrings, you can simply rebuild the documentation. The utils/generate_rst.py script will be triggered automatically:

export PYTHONPATH=$PYTHONPATH:.
rm -rf ./build
sphinx-build -M html source build