Working with the Documentation#

This project uses Sphinx to generate its documentation, powered by the MyST Parser (to write in Markdown instead of reStructuredText) and the PyData Sphinx Theme. We use uv to manage the isolated environment and dependencies.

How to Build the Pages Locally#

You don’t need to install Sphinx globally. uv will handle downloading the dependencies and executing the build in an isolated environment.

To build the HTML documentation once:

# This reads the source files in docs/ and outputs the website to docs/_build/html
uv run sphinx-build -b html docs/ docs/_build/html

To clean the build and start fresh (useful if navigation or AutoAPI gets stuck):

rm -rf docs/_build docs/autoapi
uv run sphinx-build -b html docs/ docs/_build/html

Live Preview (Recommended for writing): If you want the browser to automatically reload every time you save a .md or .py file, use the autobuild command:

uv run sphinx-autobuild docs/ docs/_build/html

How to Add New Content#

Because we use the MyST parser, you can write all your static pages in standard Markdown (.md).

  1. Create a new Markdown file inside the docs/ directory (e.g., docs/tutorial.md).

  2. Link it in the Table of Contents: Open docs/index.rst (or index.md) and add the filename (without the .md extension) to the toctree directive so it shows up in the sidebar. If you want Sphinx to auto-number the sections, just add the :numbered: flag:

.. toctree::
   :maxdepth: 2
   :numbered:
   :caption: Contents:

   tutorial
   scripts

Using Sphinx Features in Markdown: MyST allows you to use Sphinx directives inside Markdown using “fenced” code blocks. For example, to create a dropdown menu (powered by sphinx_design):

```{dropdown} Click here for more info!
This is hidden content.


## How Docstrings are Parsed and Added

You do **not** need to manually document the Python modules in `src/mypkgs/`.

We use **`sphinx-autoapi`**, which statically parses our Python code and automatically generates the "API Reference" section of the website.

### Writing Docstrings

We strictly follow the **NumPy Docstring Standard**. AutoAPI (via Napoleon) parses these sections automatically.

```python
def calculate_area(length: float, width: float) -> float:
    """
    Calculate the area of a rectangle.

    Parameters
    ----------
    length : float
        The length of the rectangle.
    width : float
        The width of the rectangle.

    Returns
    -------
    float
        The calculated area.
    """
    return length * width

Cross-Referencing#

You can hyperlink to other functions, classes, or external libraries (like NumPy or Python built-ins) directly in your docstrings or .md files using Intersphinx roles:

  • Functions:

    :func:`mypkgs.utils.get_config`

  • Classes:

    :class:`numpy.ndarray`

  • Objects/Attributes:

    :obj:`~numpy.matmul`

    (Use the tilde~ to hide the module prefix in the rendered text!)

When you hover over links to our own code (or ReadTheDocs-hosted libraries like Rasterio), sphinx-tippy will display a live preview tooltip.

Deployment to GitHub Pages#

File location: .github/workflows/deployDocs.yml

This is the GitHub Actions workflow file. It uses uv to set up the environment, builds the Sphinx docs, and uses GitHub’s official Pages actions to deploy the static HTML.