Metadata-Version: 2.4
Name: sphinxcontrib-waterloo-docstrings
Version: 0.4.0
Summary: Sphinx extension for Waterloo Docstrings
Author: Uwe
License-Expression: BSD-2-Clause
Project-URL: Homepage, https://github.com/uwe-at-sdv/sdv_doc_waterloo
Project-URL: Source, https://github.com/uwe-at-sdv/sdv_doc_waterloo/tree/sphinx
Project-URL: Issues, https://github.com/uwe-at-sdv/sdv_doc_waterloo/issues
Keywords: docstrings,documentation,normativity,sphinx,waterloo
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sdv-doc-waterloo<0.13,>=0.12
Provides-Extra: sphinx
Requires-Dist: sphinx; extra == "sphinx"
Dynamic: license-file

<p align="center">
	<img src="https://raw.githubusercontent.com/uwe-at-sdv/sdv_doc_waterloo/main/img/wtrl_logo_color.svg" alt="Waterloo Logo" width="160">
</p>

# Sphinx-Contrib Waterloo Docstrings

![License](https://img.shields.io/badge/license-BSD--2--Clause-blue)
![Version](https://img.shields.io/badge/version-0.4.0-orange)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![Sphinx](https://img.shields.io/badge/Sphinx-extension-0A507A)
[![GitHub](https://img.shields.io/badge/GitHub-sdv_doc_waterloo%40sphinx-181717?logo=github)](https://github.com/uwe-at-sdv/sdv_doc_waterloo/tree/sphinx)

# 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:

```bash
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`:

```python
extensions = [
    "sphinxcontrib.waterloo_docstrings",
]
```
