Smoke documentation

Add your content using reStructuredText syntax. See the reStructuredText documentation for details.

Preamble	normative sections Contract
Contract	general Must provide a smoke test for the Sphinx extension
«Module»	mymodule

Preamble	normative sections Contract
Contract	general constructor
«Class»	A

Signature	mymodule.A.spam( a: int b: float ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general
Parameters	a an integer b a float
Returns	The concatentation of the string representations of a and b.
Raises	<empty>
«Method»	A.spam

Preamble	normative sections Contract, Derived from
Contract	general constructor
Derived from	A, B
«Class»	X

Error

RuleID: DOC-006

Origin: validation

Summary: Section ‘Returns’ is not allowed for profile ‘inherited_method’.

Found:

Preamble:
    normative_sections:
        Contract, Returns

Expected:

Preamble:
    <one of: { Definitions, Terminology, Contract, Description, Notes, See_also }>

Hint:

waterlint explain-section --label Preamble --profile inherited_method

Preamble	normative sections Contract, Public classes, Public functions, Public types, Public constants, Public variables, Definitions
Contract	general Must provide shared helper functions, constants, and type aliases for Waterloo docstring validation and explanation.
Public classes	Trait, Scope, Flavour, Format, Status, ConfigTraversal, DocSession, tracer, ResolveObjectError, WhitelistReason
Public functions	get_source_docstring, is_obj_annotatable, is_attr_annotated, is_attr_final, is_list_of_str, is_obj_module, is_obj_class, is_obj_function, is_obj_method_like, is_obj_named_value, is_obj_documentable, get_obj_direct_module, get_obj_name, get_obj_fully_qualified_name, get_obj_path, build_anchor, get_func_obj_from_callable, get_obj_docstring, get_obj_annotations, get_obj_decorators, gen_documentable_objects, traced_section, rule_on_fail, raise_has_no_docstring, raise_parsing_error, raise_parsing_error_expected_but_got, raise_validation_error, raise_validation_error_expected_but_got, raise_validation_error_invalid_normative_section, get_allowed_sections_for_profile, warn_parsing, warn_validation
Public types	Profile Supported profile labels for the helper layer. DocstringSubtree Recursive docstring tree node type. DocstringTree A full docstring tree represented as a list of subtree values. AnnotatableObject Objects that can be annotated by the helper layer. RuleId Rule identifier type alias. Origin Tracer origin labels. Details Tracer details payload. Scopes A set of scope values. Documentable Objects that can be traversed by the helper functions. AstDocNode An AST node type relevant for docstring extraction.
Public constants	RE_RULE_ID Regular expression for rule IDs. Undocumented: RE_RULE_ID_COMPILED, the precompiled version for performance. RE_IDENTIFIER Regular expression for identifiers. Undocumented: RE_IDENTIFIER_COMPILED, the precompiled version for performance. RE_QUALIFIED_IDENTIFIER Regular expression for qualified identifiers. Undocumented: RE_QUALIFIED_IDENTIFIER_COMPILED, the precompiled version for performance. RE_CSV_IDENTIFIERS Regular expression for comma-separated identifiers. Undocumented: RE_CSV_IDENTIFIERS_COMPILED, the precompiled version for performance. WTRL_MARKUP_ROLES Regular expression for Waterloo markup roles in backtick markup. RE_WTRL_MARKUP_BACKTICK Regular expression for matching Waterloo backtick markup with roles. Undocumented: RE_WTRL_MARKUP_BACKTICK_COMPILED, the precompiled version for performance. RE_WTRL_ANGLE_HTTPS_REF Regular expression for matching Waterloo angle bracket HTTPS references. Undocumented: RE_WTRL_ANGLE_HTTPS_REF_COMPILED, the precompiled version for performance. References consist of two parts: clear text and <link>, optionally separated by whitespace. RE_WTRL_ANGLE_WTRL_REF Regular expression for matching Waterloo angle bracket wtrl references. Undocumented: RE_WTRL_ANGLE_WTRL_REF_COMPILED, the precompiled version for performance. References consist of two parts: clear text and <link>, optionally separated by whitespace. RE_WTRL_JSON_SCHEMA_NAME Regular expression for matching Waterloo JSON Schema filenames. Undocumented: RE_WTRL_JSON_SCHEMA_NAME_COMPILED, the precompiled version for performance. RULE_ID_WHITELIST Whitelist reasons for legacy rule identifiers used by the helper layer. CANONICAL_ORDER_OF_SECTIONS Canonical subsection ordering for section snippets and expected snippets. CANONICAL_ORDER_OF_PROFILES Canonical profile ordering for CLI help and documentation. TRAIT_TAG_MAP Trait tag mapping for trait labels. SCOPE_TAG_MAP Scope tag mapping for visibility selection. FLAVOUR_TAG_MAP Flavour tag mapping for normativity keyword rendering. FORMAT_TAG_MAP Output format tag mapping for string-related output. STATUS_TAG_MAP Status tag mapping for Preamble.status. SECTION_PROPERTIES Must be a mapping from section and subsection labels to their properties relevant for explanation and validation, for example body category, normativity, and profile applicability. Informative: This is a carefully distilled machine-readable representation of the relevant rules from the documentation standard, but the documentation remains the Single Source of Truth for the standard.
Public variables	SOURCE_DOCSTRING_CACHE A cache for storing source docstrings of objects to avoid redundant retrievals. OBJ_DOCSTRING_CACHE A cache for storing resolved docstring text by object identity. This cache is intentionally public so callers may inspect, clear, or replace it during a process lifetime.
Definitions	ABC Definition of ABC for testing markup roles.
Notes	Render functions The render functions in this module are intended for building verbose diagnostic messages that include source and expected snippets along with suggestions on how to fix the docstring. Markup roles This section is a test for markup roles. ABC — |attr|, for attributes in XML, keys in JSON… ABC — |class|, classes ABC — |cmd|, commands and subcommand with CLI ABC — |dfn|, a term being defined /path/to/ABC — |file|, files but also URLs ABC — |func|, functions CTRL — |key|, keys on the keyboard ABC — |label|, titles, labels ABC — |lit|, catch-all for literal text ABC — |mod|, modules should — |norm|, normativity keywords (meta, when talking about keywords) >> — |op|, operators --abc — |opt|, options for CLI commands sdv.tty — |pkg|, packages ABC — |tag|, enum values, symbolic values ABC — |term|, referencing a term defined in Definitions float — |type|, types in programming or markup languages https://pypi.org/project/sdv-doc-waterloo/ — |url|, for URLs (currently pretty simple) 12345 — |value|, R-values, unnamed values xyz — |var|, variables, but also named constants xyz: float — |var_type|, variable and type with colon.
«Module»	sdv.doc.waterloo.docitem_helper

Waterloo module context

Classes and functions below this point implicitly belong to package/module sdv.doc.waterloo.

Preamble	normative sections Contract, Public types, Public classes, Public methods
Terminology	rules on fail Low-level functions may find a parsing or validation warning or error, but have no clue which rule has been violated. The rules on fail mechanism allows the caller to pass the set of rules in question. The tracer provides a stack and api for these rule sets.
Contract	general Must provide a string-valued stack API for storing context data, like “which object/section/subsection are we in?”. Must provide a to-string method for rendering the context. Must maintain a list of infos, where each entry is a tuple consisting of context, origin, and a free-form message. Must provide a method for adding such a info entry. Must allow to query if infos have been added. Must provide a method for clearing the list of infos. Must provide a method for rendering the list of infos as a string. Must provide a generator which allows iterating over the list of infos. Must maintain a list of warnings, where each entry is a tuple consisting of context, one Rule-ID, origin, a free-form message, and optional details. Must provide a method for adding such a warning entry. Must allow to query if warnings have been added. Must provide a method for clearing the list of warnings. Must provide a method for rendering the list of warnings as a string. Must provide a generator which allows iterating over the list of warnings. Must maintain a list of errors, where each entry is a tuple consisting of context, one Rule-ID, origin, a free-form message, and optional details. Must provide a method for adding such a error entry. Must allow to query if errors have been added. Must provide a method for clearing the list of errors. Must provide a method for rendering the list of errors as a string. Must provide a generator which allows iterating over the list of errors. Must manage a set of ignore-rule instructions Must provide a stack containing the current rule on fail being validated against. Must provide an api like push..., pop..., get... for the rule on fail stack. Must provide a stack containing the current set of scopes being validated against. Must provide an api like push..., pop..., get... for the scopes stack. constructor Must be default-constructible.
Public types	Context A list of strings built per context manager during parsing and validation. Entries can be module, class or function names, or labels.
Public classes	Severity
Class overview	Severity An enum with values DEBUG, INFO, WARNING, ERROR for filtering the output of the tracer.
Public methods	build_json, str_by_severity
Method overview	build_json Build a JSON-serializable dict containing the information in the tracer, filtered by severity and optionally enriched by metadata.
Notes	Last review 2026-06-21 Parameter ‘details’ The details payload is important for the MCP server, because it gives the LLM enough debugging context to interpret tracer output and decide how to react to it. It usually is a dict with keys “found”, “expected”, and “hint”; “hint” typically contains a waterlint call for retrieving more information about the affected section or subsection.
«Class»	tracer

Waterloo class context

Methods below this point implicitly belong to class docitem_helper.tracer.

Signature	sdv.doc.waterloo.docitem_helper.tracer.build_json( severity: Severity schema_version: str | None = None waterloo_version: str | None = None id_prefix: str | None = None include_debug: bool = True ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build a JSON-serializable dict containing the tracer’s data, following the WTRL Tracer JSON Schema. Must include entries up to the specified severity level. Must allow including debug notes optionally, as they may contain sensitive or verbose information. Must include schema version and optionally Waterloo version in the metadata section.
Parameters	severity Only include entries with this severity level or higher. Levels are ordered as DEBUG < INFO < WARNING < ERROR. schema_version Specify the WTRL Tracer JSON Schema version to declare in the output. Defaults to the current version if not provided. This does not affect the structure of the output, which always follows the current schema. Including the schema version allows consumers to validate against the correct schema and maintain compatibility as the schema evolves. Must be a string in the format X.Y.Z where X, Y, and Z are non-negative integers. Must default to the current schema version if not provided. Must be included in the output under the `__WTRL_VERSION__` metadata section. Must not affect the actual structure of the output, which always follows the current schema. waterloo_version Optionally include the version of the Waterloo tool that generated the tracer data. Must be a string in the format X.Y.Z where X, Y, and Z are non-negative integers. id_prefix Optionally include a prefix for the `$id` field in the output JSON. Must be a string if provided. May be omitted, in which case the `$id` field will not include a prefix. include_debug Optionally include debug notes in the output JSON.
Returns	A JSON-serializable dict containing the tracer’s data structured according to the WTRL Tracer JSON Schema, including entries up to the specified severity level and metadata about the schema and optionally the Waterloo version. The return value must conform to JSON Schema :file:`wtrl-tracer-json-X.Y.Z.schema.json` where X.Y.Z is the declared schema version.
Raises	<empty>
«Method»	tracer.build_json

Waterloo class context

Default class qualifier docitem_helper.tracer ends here. No default class active.

Waterloo module context

Default module qualifier sdv.doc.waterloo ends here. No default module active.