2. Getting Started¶

Suppose you are about to build a Python module or write documentation for an existing one. This section demonstrates how to get started with Waterloo Docstrings.

We use Sphinx as the primary documentation system to generate human-readable documentation, and Waterloo’s command-line tool waterlint to produce machine-readable output from the original Python docstrings.

If you are only interested in machine-readable documentation, you may skip sections Install Sphinx and Building a Human-Readable Documentation.

2.1. Setup Root Directory¶

In the following sections, we refer to the project’s root directory as ${ROOT}. Navigate to this directory in your terminal before proceeding.

We use the placeholder name my_module for the module to be documented (and as a prefix for related files), and my_module.py for the corresponding source file.

2.2. Virtual Environment¶

We recommend using a Python virtual environment for the initial setup. This prevents upgrades of your system-wide installations of pip, sphinx, and other packages, which may not be desirable.

2.2.1. Create a Virtual Environment¶

There is extensive documentation available for venv, but since it is straightforward to use, we briefly summarize the basic steps here.

Make sure you are in your project directory, then run:

python3 -m venv venv_wtrl

This creates a directory venv_wtrl containing a standard Python installation.

2.2.2. Activate the Environment¶

Run the activation command appropriate for your operating system and shell.

Activation Commands¶
Platform	Shell	Command
Unix / macOS	Bash / Zsh	`source venv_wtrl/bin/activate`
	Fish	`source venv_wtrl/bin/activate.fish`
	csh/tcsh	`source venv_wtrl/bin/activate.csh`
Windows	PowerShell	`./venv_wtrl/Scripts/Activate.ps1`
	Command Prompt	`venv_wtrl/Scripts/activate.bat`
	Git Bash	`source venv_wtrl/Scripts/activate`

Note

Windows / PowerShell: If you encounter an execution policy error, allow script execution for the current session by running:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Leave the environment using deactivate when you are finished with this tutorial.

2.3. Install Sphinx¶

You have likely already installed Sphinx. However, if you are working inside the virtual environment recommended above, you need to install it there as well.

First, ensure that you are using the latest version of pip:

python3 -m pip install --upgrade pip

Note

If python3 -m pip is not available inside the activated environment, bootstrap pip first:

python3 -m ensurepip --upgrade

Then install Sphinx and any extensions required for your project:

python3 -m pip install sphinx

You are still in the project’s root directory. Create a directory for the human-readable documentation:

mkdir doc
cd doc

Initialize a Sphinx project, for example using sphinx-quickstart:

sphinx-quickstart

> Separate source and build directories (y/n) [n]: y
> Project name: My-Project
> Author name(s): My-Name
> Project release []: 0.0.1

Waterloo is currently not multilingual, so we use English as the project language:

> Project language [en]:

Build the documentation to verify the setup:

make clean && make html

Open the generated documentation in your browser (replace ${ROOT} with your project’s root directory):

file://${ROOT}/doc/build/html/index.html

2.4. Waterloo Docstrings¶

2.4.1. Install Waterloo Docstrings¶

If you have not done so already, update pip:

python3 -m pip install --upgrade pip

Install Waterloo from PyPI:

python3 -m pip install sdv-doc-waterloo

If you want to work from the current source tree, install from GitHub via HTTPS:

python3 -m pip install git+https://github.com/uwe-at-sdv/sdv_doc_waterloo.git

Add the extension to ${ROOT}/doc/source/conf.py:

# -- General configuration -------------------------------------

extensions = [
        # other extensions
        "sdv.doc.waterloo.docitem_sphinx",
]

Configure the path to your project sources:

# -- Path setup ------------------------------------------------

# If your modules are located outside the documentation directory,
# add their paths here. Use os.path.abspath to convert relative
# paths to absolute ones if necessary.
import sys

ROOT = "/path/to/my/project"
sys.path.insert(0, ROOT)

2.4.2. Adding a Waterloo Docstring¶

Insert the following example docstring at the top of your module source file my_module.py.

Indentation may use either a tab character or four spaces. In this example, four spaces are used for convenience.

r"""
Preamble:
    profile:
        module
    normative_sections:
        Contract
Contract:
    general:
        |Must| serve as an example for a Waterloo docstring.
"""

The next step is important and should be applied to every docstring you write: validate it formally.

While the Waterloo Sphinx extension can detect structural errors, the linter provides more detailed and clearer diagnostics.

waterlint validate --basedir . --obj my_module

2.4.3. Building a Human-Readable Documentation¶

To see how Waterloo integrates with Sphinx, add the following directive to a source file, for example index.rst (for testing purposes):

.. wtrl_autodoc_module:: my_module

Build the documentation:

make clean && make html

In your browser, you should now see a compact and structured representation of the module docstring.

Other object types (such as classes and functions) can be added in the same way using the corresponding directives.

2.4.4. Building a Machine-Readable Documentation¶

As outlined in the introduction, LLMs can process the original Waterloo docstrings directly. However, JSON is often preferred because it is not indentation-based and can be validated using established JSON schema mechanisms.

Create a directory for the JSON output. Since Waterloo Docstrings is a relatively new project (2026), no established best practice exists yet. We recommend naming the directory “doc-json” so that AI agents can locate it easily. Navigate back to your project directory and run:

mkdir doc-json

Render the module documentation in JSON format:

waterlint render-json --basedir . --obj my_module --out-dir doc-json

Validate the generated JSON file:

waterlint validate-json --in doc-json/my_module.wtrl.core.rfc-2119.json

If no error message is shown and the exit code is 0, the JSON output is valid.

To list the installed Waterloo JSON schemas, run:

waterlint list-schemas

2.5. Final Remarks¶

This section outlines the minimal steps required to integrate Waterloo Docstrings into a project.

Further examples are provided in Examples and Docstrings - minimal and full examples.

The formal specification of the format is given in Docstring format.