Edit the DEA Tools documentation

The DEA Tools documentation on the Knowledge Hub is automatically generated from 'docstrings' within the DEA Tools codebase. Therefore, to edit this documentation, you will need to edit the docstrings within these Python code files. This guide will explain how to edit this documentation and also the technical details of how it is generated.

Edit the documentation

1. Create a new branch. (You'll need to use the same Git workflow as when editing a DEA Notebook.)
2. In the dea-notebooks repository, navigate to Tools/dea_tools. This folder contains a file for each module of the DEA Tools package. You'll notice that each of these files has its own documentation page on the Knowledge Hub.
3. Open any file in your text editor. In this example, we will open climate.py which has the documentation page dea_tools.climate.
4. Edit any of the docstrings in this file. (Learn about the docstring format below.)
5. Push your changes. Once they are eventually merged into the stable branch, the Knowledge Hub will automatically rebuild to display your changes.

• If you add a new dependency to setup.py, you must also remember to add it to mock_imports.txt in the dea-docs repository. (It's inside the docs folder.) If you forget to do this, the relevant API documentation pages will disappear from the Knowledge Hub!

Docstring format (Numpy)

The docstring format is the syntax for writing docstrings that allows you to define the parameters and return values of functions, as well as other software constructs. The DEA Tools package uses the Numpy format for docstrings (instead of the default 'Restructured Text' format).

Here's an example — the docstring for the era5_area_crop method in the 'climate' module.

def era5_area_crop(ds, lat, lon):
    """
    Crop a dataset containing European Centre for Medium Range Weather
    Forecasts (ECMWF) global climate reanalysis product (ERA5) variables
    to a location.

    The output spatial grid will either include input grid points within
    lat/lon boundaries or the nearest point if none is within the search
    location.

    Parameters
    ----------
    ds : xarray dataset
        A dataset containing ERA5 variables of interest.

    lat : tuple or list
        Latitude range for query.

    lon : tuple or list
        Longitude range for query.

    Returns
    -------
    An xarray dataset containing ERA5 variables for the selected
    location.

    """

The docstring contains a summary section followed by a list of Parameters followed by a list of Returns (return values). To learn more about this format and its various features, see the Numpy Style Guide.

How the pages are generated

This section explains the technical details of how the DEA Tools documentation pages are generated on the Knowledge Hub. This site uses several Sphinx extensions to do this.

• sphinx.ext.autodoc — The Autodoc extension processes the
• sphinx.ext.autosummary — The Autosummary extension
• sphinx.ext.napoleon — the Napoleon extension

The autodoc extension imports the dea-tools Python modules and processes the docstrings into pages of content on the Knowledge Hub. The autosummary extension adds an automatically generated list of links to the content pages to link to each of the modules and functions. The napoleon extension allows us to write docstrings using Numpy format instead of the standard docstring format.