sphinxcontrib-waterloo-docstrings 0.5.0

Sphinx extension for Waterloo Docstrings

Sphinx-Contrib Waterloo Docstrings

This branch is under development

The sphinxcontrib-waterloo-docstrings package provides the Sphinx rendering layer for Waterloo Docstrings.

Waterloo Docstrings define a structured docstring format with explicit section semantics, normativity rules, and machine-readable output layers. This package connects that format to Sphinx by providing roles, directives, and rendering helpers for documentation projects that want to present Waterloo docstrings as human-readable HTML.

The extension is intentionally theme-friendly. It lets Sphinx themes such as Furo, Alabaster, and Classic provide most of the final layout, while the extension supplies semantic CSS classes for Waterloo roles and generated documentation structures.

What it provides

• Sphinx roles for Waterloo inline markup.
• Directives for rendering modules, classes, functions, methods, and context scopes.
• Static CSS for Waterloo semantic roles.
• Theme showcase sources for Furo, Alabaster, and Classic.

Related packages

• sdv-doc-waterloo: core parser, validator, renderer, waterlint, and MCP server.
• python-waterloo-lexer: Pygments lexer for Python files with Waterloo docstrings.

Documentation showcase

The public project documentation is published at:

• https://uwe-at-sdv.github.io/sdv_doc_waterloo/

The Sphinx extension showcase is planned under:

• https://uwe-at-sdv.github.io/sdv_doc_waterloo/sphinx/furo/
• https://uwe-at-sdv.github.io/sdv_doc_waterloo/sphinx/alabaster/
• https://uwe-at-sdv.github.io/sdv_doc_waterloo/sphinx/classic/

Installation

Install the Sphinx extension from PyPI:

pip install sphinxcontrib-waterloo-docstrings

The package depends on sdv-doc-waterloo and provides the Sphinx integration layer for Waterloo Docstrings.

Quick check

After installation, add the extension to a Sphinx conf.py:

extensions = [
    "sphinxcontrib.waterloo_docstrings",
]