3. Configuration¶

The extension is configured through ordinary Sphinx configuration variables in the project’s conf.py file. The values are read when Sphinx starts building the documentation, so changes normally require a fresh Sphinx build.

This documentation uses the following Waterloo-specific settings:

wtrl_diagnostics_admonitions_enabled = True
wtrl_diagnostics_logging_enabled = True
wtrl_diagnostics_color_enabled = True
wtrl_current_object_logging_enabled = False
wtrl_scope_filtered_object_placeholders_enabled = True
wtrl_state_change_admonitions_enabled = True
wtrl_state_change_logging_enabled = True

The following sections describe the implemented configuration variables.

3.1. Diagnostics¶

These variables control how the extension reports invalid directive usage, failed object resolution, and Waterloo validation errors.

wtrl_diagnostics_admonitions_enabled [Default: True] – Controls whether diagnostic messages are rendered into the generated document as admonitions. This is useful while authoring documentation because the error appears close to the directive that caused it. Chapter Admonitions shows examples of these rendered diagnostics.

wtrl_diagnostics_logging_enabled [Default: True] – Controls whether diagnostics are also emitted through Sphinx’s standard logging channel. This is the build-terminal counterpart to diagnostic admonitions and is usually the right place to look in automated builds.

Example:

----- Tracer-----8<---------------------------------------------
- Error [validation] - [doc_errors.X_bad_contract->Contract]
  [Rule CON-023] Subsection 'general' does not exist.
found:
        Contract:
expected:
        Contract:
                general:
                        ...
hint:
        waterlint explain-subsection --label Contract.general --profile class
----- Tracer----->8---------------------------------------------

wtrl_diagnostics_color_enabled [Default: False] – Enables ANSI coloring for structured validation diagnostics in the Sphinx log output. Leave this disabled when the build output is captured by tools that do not preserve ANSI escape sequences.
wtrl_current_object_logging_enabled [Default: False] – Logs the object currently being resolved, validated, or rendered. This is mainly a debugging aid for large documents where a later diagnostic does not make the active object obvious enough.

3.2. State And Scope¶

The Waterloo directives maintain a small build-time state: current module, current class, and current documentation scope. The following variables control how visible changes to that state are in the generated document and in the build log.

wtrl_scope_filtered_object_placeholders_enabled [Default: True] – Controls whether objects filtered out by scope are represented by a small placeholder admonition. Without this placeholder the object simply disappears from the rendered document. With the placeholder enabled, the omission remains visible and easier to audit. An example is shown in subsection Out of scope.

The active scope is controlled by state-changing directives as described in section State changing directives.
wtrl_state_change_admonitions_enabled [Default: True] – Controls whether state-changing directives are rendered into the generated document. This can look verbose in finished prose, but it makes normative documentation easier to inspect because changes of module, class, and scope are visible in the artifact itself.
wtrl_state_change_logging_enabled [Default: True] – Controls whether state-changing directives are logged during the Sphinx build.

3.3. Import Resolution¶

wtrl_basedirs [Default: [] – empty list] – Lists directories that are added to sys.path before Waterloo resolves module and object identifiers. Each path is resolved to an absolute path and inserted at the front of sys.path if it is not already present.

Use this variable for local example modules, generated modules, or project sources that are not installed in the Python environment used to run Sphinx. For this documentation, conf.py computes the path to examples-python relative to the configuration file:
```
from pathlib import Path

CONF_DIR = Path(__file__).resolve().parent
path_to_examples = str((CONF_DIR / ".." / ".." / "examples-python").resolve())
wtrl_basedirs = [
        path_to_examples
        ]
```
Installed packages usually do not need an entry in wtrl_basedirs. They only need to be importable by the same Python interpreter that runs the Sphinx build.

3.4. Sphinx Setup Hook¶

Some Sphinx configuration cannot be expressed as plain configuration variables. For these cases Sphinx looks for a function named setup in conf.py. The Waterloo documentation uses this hook to register the Python-Waterloo Pygments lexer:

from python_waterloo_lexer import PythonWaterlooLexer

def setup(app: Any) -> dict[str, Any]:
        app.add_lexer("python", PythonWaterlooLexer)
        app.add_lexer("python-waterloo", PythonWaterlooLexer)

The two calls serve different purposes.

Registering the lexer as python replaces Sphinx’s default Python highlighting for ordinary Python code blocks:

.. code-block:: python

This is convenient when most Python snippets in the documentation contain Waterloo docstrings or Waterloo inline markup. It also makes existing Python code blocks benefit from the Waterloo-aware lexer without changing the source files.

Registering the lexer as python-waterloo creates an explicit language name:

.. code-block:: python-waterloo

This is the more conservative option. Use it when the documentation contains ordinary Python snippets that should keep Sphinx’s default Python highlighting, and only selected examples should use the Waterloo-aware lexer.

You can register either name or both names. Registering both is useful in documentation that mostly shows Waterloo-aware Python code but still wants an explicit python-waterloo language for examples and tests.

Syntax highlighting colors are still controlled by Sphinx’s ordinary Pygments configuration variables. With themes that support light and dark mode, such as Furo, configure both variants explicitly:

pygments_style = "autumn"
pygments_dark_style = "gruvbox-dark"

The first value is used for the light color scheme. The second value is used for the dark color scheme. If only pygments_style is configured, the dark-mode output may use a Sphinx or theme fallback that does not match the style being tested in light mode.

Examples of syntax highlighting with the Waterloo-aware lexer are shown in chapter Miscellaneous.