2. Getting Started¶

This chapter shows the minimal path from a Python module with a Waterloo docstring to rendered Sphinx documentation. It assumes a small project and uses explicit placeholder paths so that the individual steps remain easy to adapt.

The goal is not to explain every Sphinx option. The goal is to create a working documentation build that loads sphinxcontrib-waterloo-docstrings, finds your Python module, and renders one Waterloo docstring.

2.1. Choose The Directories¶

The examples below use two placeholder directories:

/path/to/PROJECT_DIR – the directory that contains the Python module you want to document.
/path/to/DOC_DIR – the directory in which the Sphinx documentation project will be created.

The module used in this tutorial is called my_module. Its source file is therefore:

/path/to/PROJECT_DIR/my_module.py

Run the setup commands from /path/to/DOC_DIR unless noted otherwise.

2.2. Create A Virtual Environment¶

Using a Python virtual environment is recommended for the first setup. It keeps Sphinx, Waterloo, and related packages separate from the system-wide Python installation.

Create the environment in /path/to/DOC_DIR:

python3 -m venv venv_wtrl

Activate it with the 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 activation fails because of the execution policy, allow script execution for the current user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Leave the environment with deactivate when you are finished.

2.3. Install The Extension¶

Inside the activated virtual environment, make sure pip is available and reasonably up to date:

python3 -m pip install --upgrade pip

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

python3 -m ensurepip --upgrade

Install Sphinx and the Waterloo Sphinx extension:

python3 -m pip install sphinx sphinxcontrib-waterloo-docstrings

The extension depends on sdv-doc-waterloo; this dependency is installed automatically.

2.4. Create A Sphinx Project¶

Still in /path/to/DOC_DIR, create a directory for the Sphinx project and switch into it:

mkdir doc
cd doc

Initialize the Sphinx project:

sphinx-quickstart

For this tutorial, choose separate source and build directories:

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

Separate source and build directories are not required by Waterloo, but they make the tutorial layout explicit and keep generated files out of the source tree.

Build the generated Sphinx skeleton once:

make clean && make html

Open the generated documentation in your browser:

file:///path/to/DOC_DIR/doc/build/html/index.html

2.5. Enable Waterloo In Sphinx¶

Add the extension to /path/to/DOC_DIR/doc/source/conf.py:

extensions = [
        # other extensions
        "sphinxcontrib.waterloo_docstrings",
        ]

Tell the extension where your project sources are located:

wtrl_basedirs = [
        "/path/to/PROJECT_DIR",
        ]

The paths listed in wtrl_basedirs are added to sys.path during the Sphinx build. Installed packages usually do not need an entry here; local source directories usually do.

2.6. Add A Waterloo Docstring¶

Create or edit /path/to/PROJECT_DIR/my_module.py and insert the following module docstring:

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

Waterloo indentation may use either one tab or four spaces per indentation level. The example above uses tabs because they make the logical structure compact in source form.

Before rendering, validate the docstring:

waterlint validate --basedir /path/to/PROJECT_DIR --obj my_module

The --obj option expects a Python module, class, function, or method identifier, not a filename.

2.7. Render The Docstring¶

Add the Waterloo directive to a Sphinx source file, for example /path/to/DOC_DIR/doc/source/index.rst:

.. wtrl_autodoc_module:: my_module

Build the documentation again:

make clean && make html

The generated HTML page should now contain a compact, structured rendering of the module docstring.

2.8. Optional Theme Notes¶

The extension ships default styles that work with the tested themes classic, alabaster, and furo. Theme-specific styling is not required for the first build.

For alabaster, the package contains an optional stylesheet that varies the Alabaster theme. It adapts the page layout to documentation with long section names, such as fully qualified identifiers, and has a visible effect on the rendering of Waterloo docstring boxes:

html_css_files = [
        # other project stylesheets
        "waterloo_alabaster.css",
        ]

Most themes support html_favicon. If you do not provide your own favicon, you may use the Waterloo favicon:

html_favicon = "_static/favicon.ico"

See CSS Customization for details about roles, dark-mode variables, and generated CSS classes.