1. Introduction

1.1. What This Extension Does

This package provides a Sphinx extension for rendering Waterloo Docstrings as HTML documentation. It adds directives for inserting Waterloo docstrings into a Sphinx document and roles for rendering Waterloo’s semantic inline markup.

During rendering, the extension resolves Python objects, reads their docstrings, parses the Waterloo structure, validates the result, and converts the validated docstring into Docutils nodes. If something goes wrong, the extension can show diagnostics directly in the generated document and also report them through the Sphinx build log.

1.2. Why Waterloo Docstrings

Waterloo Docstrings define a structured docstring format for Python projects. The format focuses on machine-verifiable normativity: requirements and guarantees are not merely written as prose, but anchored in explicitly defined sections, subsections, and normativity keywords.

This matters when documentation is consumed by both humans and tools. A human reader should see readable reference documentation. A tool, validator, or LLM should be able to inspect the same source text and recover enough structure to reason about contracts, parameters, return values, examples, and cross references.

The normative Waterloo documentation describes the format in detail and shows examples of valid docstrings:

Waterloo Docstrings documentation

1.3. Design Goals

The extension is designed as a rendering layer for Waterloo Docstrings, not as a separate documentation format. Its main goals are:

  • Render validated Waterloo docstrings into ordinary Sphinx/Docutils nodes.

  • Keep semantic markup visible in the HTML output without turning it into purely typographic decoration.

  • Report resolver, parser, and validator diagnostics close to the source directive that triggered them.

  • Stay reasonably theme-neutral, so the generated output can follow the visual language of the active Sphinx theme.

  • Preserve a practical authoring workflow: write Python docstrings, validate them with Waterloo validation tools, and render them through Sphinx.

The extension deliberately leaves the normative definition of the docstring format to the Waterloo documentation. This package focuses on how validated Waterloo docstrings are embedded into a Sphinx project.

1.4. What This Extension Is Not

This extension is not the normative definition of the Waterloo Docstring format. The rules for valid sections, subsections, indentation, scopes, normativity keywords, and diagnostics belong to the Waterloo documentation and the Waterloo validation tools.

The directive names are intentionally close to sphinx.ext.autodoc: both systems resolve Python objects and generate Sphinx documentation from their docstrings. The difference is that this extension does not interpret arbitrary Python docstrings. It expects Waterloo docstrings, validates their structure, and renders their semantic content.

In particular, this package does not try to infer missing documentation from Python signatures or source code. If a docstring is missing, malformed, or invalid, the renderer reports that problem instead of silently inventing documentation.

1.5. How It Fits Into Waterloo

This package is one output layer in the broader Waterloo toolchain. The core Waterloo package defines the docstring model, parses Waterloo text, validates the structure, and provides diagnostics that can be consumed by humans or tools.

Other parts of the toolchain focus on different output targets: structured JSON for machine consumers, interactive HTML for browsing generated documentation, and MCP access for LLM-assisted workflows. This Sphinx extension focuses on a different integration point: it embeds validated Waterloo docstrings into a normal Sphinx project, so they can be combined with hand-written prose, cross-references, themes, and the rest of the Sphinx ecosystem.

1.6. Project Status

The extension is type-checked regularly with mypy. The checked source files are:

sphinxcontrib/waterloo_docstrings/wtrl_protocol.py
sphinxcontrib/waterloo_docstrings/wtrl_parse.py
sphinxcontrib/waterloo_docstrings/wtrl_state.py
sphinxcontrib/waterloo_docstrings/wtrl_markup.py
sphinxcontrib/waterloo_docstrings/wtrl_signature.py
sphinxcontrib/waterloo_docstrings/wtrl_autodoc.py
sphinxcontrib/waterloo_docstrings/__init__.py
sphinxcontrib/waterloo_docstrings/wtrl_context.py
sphinxcontrib/waterloo_docstrings/wtrl_directives.py
sphinxcontrib/waterloo_docstrings/extension.py
sphinxcontrib/waterloo_docstrings/wtrl_roles.py

The current type-checking status is:

Success: no issues found in 11 source files

The mypy configuration used for this report is:

[mypy]
python_version = 3.10
ignore_missing_imports = True
follow_imports = silent
strict_optional = True
show_error_codes = True
warn_unused_ignores = True
disallow_untyped_defs = True
allow_redefinition = False
no_implicit_optional = True
warn_return_any = True
disallow_any_generics = True
warn_unreachable = True
warn_unused_configs = True
warn_redundant_casts = True
strict_equality = True

Known type-checking exceptions are listed here:

1.7. Dependencies

The package depends on sdv-doc-waterloo, which provides the Waterloo parser, validator, diagnostics, and rendering helpers used by this extension.

The Sphinx dependency itself is provided as an optional extra in the package metadata. This keeps the dependency relationship explicit: the extension code depends on the Waterloo core package, while a project that actually builds Sphinx documentation also needs Sphinx installed in the build environment.

Installation details are covered in Getting Started.