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

Firstly, here's what you will need to do to edit the documentation for an existing function in the code.

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.

Whenever you add a new function to the DEA Tools package, you should remember to write a docstring. Otherwise, the function will be undocumented!

⚠️ Warning
Whenever you add a new dependency to the project in setup.py, you must also remember to add the dependency to mock_imports.txt. Otherwise, pages of the DEA Tools documentation that rely on the new dependency will disappear!

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 function 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 (with data types) followed by a list of Returns (return values). It's important to document all of the function's parameters (in this case ds, lat, and lon). Restructured Text formatting can be used including ``monospace font`` and `hyperlinks <https://example.com/>`_.

To learn more about this format and its full capabilities, see the Numpy Style Guide.

How it works

The DEA Tools pages on the Knowledge Hub are generated by using several Sphinx extensions.

• sphinx.ext.autodoc — The Autodoc extension pulls the docstrings from the Python modules into the website.
• sphinx.ext.autosummary — The Autosummary extension generates lists of links pointing to the various pages and their functions and other software constructs.
• sphinx.ext.napoleon — The Napoleon extension allows us to write docstrings in the Numpy format instead of the default format.