9. Reference

This chapter presents the self-referential documentation of the Sphinx extension by means of the Sphinx extension itself. For state changes, the examples include notes that show the required reST code. Note that state changes require the fully qualified name of the module or class that is pushed to or popped from the state stack.

The code for the following state change is:

.. wtrl_push_current_scope:: core

Waterloo scope context

Scope below this point is set to core.

The code for the following state change is:

.. wtrl_push_current_module:: sphinxcontrib.waterloo_docstrings

Waterloo module context

Classes and functions below this point implicitly belong to package/module sphinxcontrib.waterloo_docstrings.

9.1. Module extension

The code for the following docstring representation is:

.. wtrl_autodoc_module:: extension

Preamble	normative sections Contract, Public classes, Public functions, Public types, Public constants
Description	This module provides the Sphinx integration layer for the Waterloo documentation system. The implementation operates directly on Docutils nodes and defines custom Docutils roles to generate structured documentation output from Waterloo-style docstrings. Sphinx is used as the execution and rendering framework, but the internal data model is based on the Docutils abstract syntax tree (AST). All document structure, including sections, tables, lists, rubrics, and inline markup, is represented using Docutils node classes. The module introduces a configurable context object which encapsulates all project-specific presentation logic, including role expansion, symbol rendering, and HTML layout decisions. This context is configured by the target project via its conf.py and is intentionally decoupled from the core implementation. To support concise and unambiguous normative documentation, the module maintains explicit scope stacks with the semantics “current module” and “current class”. These scopes define the implicit ownership of subsequently documented functions and methods and are modified using dedicated Docutils roles or directives. The primary goal of this module is correctness, completeness, and reproducibility of normative documentation. Readability and visual presentation are considered secondary and are handled through configurable rendering layers.
Terminology	Docutils node An element of the Docutils abstract syntax tree (AST), such as paragraph, section, or literal. Docutils role An inline markup construct of the form ``:role:`content``` implemented using the Docutils role API. Custom roles provided by this module are registered via Sphinx but conceptually belong to Docutils. Sphinx extension A Python module loaded by Sphinx to extend its parsing, transformation, or rendering behavior. This module is implemented as a Sphinx extension but operates primarily on Docutils data structures.
Contract	general Must provide classes and functions for buidling Docutils nodes from docstring trees. Must provide a default layout for HTML output from Sphinx. Must provide a class context which provides abstract roles to be configured by the target project’s conf.py. Must provide a function for building Docutils nodes from a module docstring in waterloo format. Must provide a function for building Docutils nodes from a function docstring in waterloo format. Must provide a function for building Docutils nodes from a class docstring in waterloo format. Must provide a function for building Docutils nodes from a class docstring and the class’ method docstrings in waterloo format. Must provide a Docutils role for rendering a function prototype. Must provide a Docutils role for rendering a method prototype. Must maintain a stack with semantics “current module” and push-, pop-, get-methods. Must maintain a stack with semantics “current class” and push-, pop-, get-methods. Must provide Docutils roles or directives for modifying these stacks.
Public classes	context, RolePara
Class overview	context A class that encapsulates Sphinx and Docutils state, configuration, and rendering logic for Waterloo docstring processing. RolePara Aggregate type for the parameters of role handler functions. RolePara is a tuple of the form (role_name, rawtext, text, lineno, inliner, options, content).
Public functions	build_sphinx_nodes, build_sphinx_nodes_full, resolve_qualified_name, wtrl_build_autodoc_module_nodes, wtrl_build_autodoc_function_nodes, wtrl_build_autodoc_class_nodes, wtrl_build_autodoc_class_full_nodes, wtrl_build_push_current_module_nodes, wtrl_build_push_current_class_nodes, wtrl_build_push_current_scope_nodes, wtrl_build_pop_current_module_nodes, wtrl_build_pop_current_class_nodes, wtrl_build_pop_current_scope_nodes, wtrl_build_method_signature_nodes, wtrl_build_function_signature_nodes, wtrl_build_method_signature_block_nodes, wtrl_build_function_signature_block_nodes, wtrl_attr_role, wtrl_class_role, wtrl_cmd_role, wtrl_dfn_role, wtrl_file_role, wtrl_func_role, wtrl_label_role, wtrl_lit_role, wtrl_mod_role, wtrl_norm_role, wtrl_op_role, wtrl_opt_role, wtrl_tag_role, wtrl_type_role, wtrl_value_role, wtrl_var_role, wtrl_var_type_role
Function overview	build_sphinx_nodes Build a list of Docutils nodes from a docstring tree. build_sphinx_nodes_full Build a list of Docutils nodes of a class object and its member functions from a docstring tree. resolve_qualified_name Analyze a qualified name and return the object it refers to plus resolved name components. wtrl_build_autodoc_module_nodes Implementation of role .. wtrl_autodoc_module:: wtrl_build_autodoc_function_nodes Implementation of role .. wtrl_autodoc_function:: wtrl_build_autodoc_class_nodes Implementation of role .. wtrl_autodoc_class:: wtrl_build_autodoc_class_full_nodes Implementation of role .. wtrl_autodoc_class_full:: wtrl_build_push_current_module_nodes Implementation of directive .. wtrl_push_current_module:: wtrl_build_push_current_class_nodes Implementation of directive .. wtrl_push_current_class:: wtrl_build_push_current_scope_nodes Implementation of directive .. wtrl_push_current_scope:: wtrl_build_pop_current_module_nodes Implementation of directive .. wtrl_pop_current_module:: wtrl_build_pop_current_class_nodes Implementation of directive .. wtrl_pop_current_class:: wtrl_build_pop_current_scope_nodes Implementation of directive .. wtrl_pop_current_scope:: wtrl_build_method_signature_nodes Implementation of directive .. wtrl_method_signature:: Render a method signature with optional class context and inline markup. Rendering in a single line can be inconvenient for long signatures; consider using wtrl_build_method_signature_block_nodes. wtrl_build_function_signature_nodes Implementation of directive .. wtrl_function_signature:: Render a function signature with inline markup. Rendering in a single line can be inconvenient for long signatures; consider using wtrl_build_function_signature_block_nodes. wtrl_build_method_signature_block_nodes Implementation of directive .. wtrl_method_signature_block:: Render a method signature with optional class context and inline markup in a block layout. wtrl_build_function_signature_block_nodes Implementation of directive .. wtrl_function_signature_block:: Render a function signature with inline markup in a block layout. wtrl_attr_role Implementation of role :wtrl_attr: wtrl_class_role Implementation of role :wtrl_class: wtrl_cmd_role Implementation of role :wtrl_cmd: wtrl_dfn_role Implementation of role :wtrl_dfn: wtrl_file_role Implementation of role :wtrl_file: wtrl_func_role Implementation of role :wtrl_func: wtrl_label_role Implementation of role :wtrl_label: wtrl_lit_role Implementation of role :wtrl_lit: wtrl_mod_role Implementation of role :wtrl_mod: wtrl_norm_role Implementation of role :wtrl_norm: wtrl_op_role Implementation of role :wtrl_op: wtrl_opt_role Implementation of role :wtrl_opt: wtrl_tag_role Implementation of role :wtrl_tag: wtrl_type_role Implementation of role :wtrl_type: wtrl_value_role Implementation of role :wtrl_value: wtrl_var_role Implementation of role :wtrl_var: wtrl_var_type_role Implementation of role :wtrl_var_type:
Public types	RoleResult Aggregate type for the return value of role handler functions. RoleResult is a tuple of the form (nodes, messages) where nodes is a list of Docutils nodes and messages is a list of Docutils system messages.
Public constants	RST_TEXT_ESCAPE_CHARS A frozenset of characters that must be escaped in reStructuredText text segments to avoid unintended markup interpretation. RST_ROLE_BODY_ESCAPE_CHARS A frozenset of characters that must be escaped in reStructuredText role bodies to avoid unintended markup interpretation. WTRL_TOKEN_REPLACEMENTS A Mapping of Waterloo token strings to their corresponding reStructuredText role expansions. This mapping is used to convert tokens like Must into the appropriate role.
Notes	Last reviewed 2026-07-16
«Module»	sphinxcontrib.waterloo_docstrings.extension

The code for the following state change is:

.. wtrl_push_current_module:: sphinxcontrib.waterloo_docstrings.extension

Waterloo module context

Classes and functions below this point implicitly belong to package/module sphinxcontrib.waterloo_docstrings.extension.

9.1.1. Helper

9.1.1.1. Function resolve_qualified_name

The code for the following docstring representation is

.. wtrl_autodoc_function:: resolve_qualified_name

Signature	sphinxcontrib.waterloo_docstrings.wtrl_state.resolve_qualified_name( ctx: context | None qname: str ) -> tuple[object, str, str, list[str]]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must resolve the qualified name qname using current module/class context in ctx when present. Must try to import the resolved object as criterion that resolution succeeded (see section Raises) Must try fully qualified forms in this order: current module + current class + qname, current module + qname, then qname as given.
Parameters	ctx The context which provides current module and current class. qname The qualified name to resolve.
Returns	Must return a tuple (obj, module_name, head_name, tail_parts) where obj is the resolved object, module_name is the imported module name, head_name is the last attribute component, and tail_parts is the attribute chain after the module components.
Raises	ImportError Must raise if the module of the qualified name cannot be resolved. ValueError Must raise if no attribute is specified after a resolved module name. BaseException Must propagate exceptions from the module import.
«Function»	resolve_qualified_name

9.1.1.2. Function resolve_markup

Signature	sphinxcontrib.waterloo_docstrings.wtrl_markup.resolve_markup( text: str ctx: context ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must convert Waterloo inline markup syntax into reStructuredText role directives. Must process both naked tokens and |role|`body` markup patterns. Must escape special RST characters in text segments while preserving markup boundaries. Must return the converted markup string ready for Sphinx processing.
Parameters	text The source text containing Waterloo markup patterns to resolve. Markup patterns include naked tokens (Must, may, True, False, etc.) and structured marks (body, e.g., str, enabled). ctx The context object providing scope information for markup resolution, used by helper functions to resolve qualified names and check visibility.
Returns	The input text with all recognized Waterloo markup patterns converted to Sphinx role syntax. Text segments outside markup are escaped for RST special characters. The returned string is ready for parsing by the Sphinx RST parser.
Raises	Exception May propagate if context operations fail during markup resolution (e.g., qualified name resolution in nested contexts).
See also	RST_TEXT_ESCAPE_CHARS, RST_ROLE_BODY_ESCAPE_CHARS, WTRL_TOKEN_REPLACEMENTS
Notes	Markup_conversion Naked tokens like ‘|’ + Must + ‘|’ → :wtrl_norm:`Must` Structured markup like ‘|’ + role + ‘|’ + `body` → :wtrl_role:`body`. Escaping Text segments outside markup use RST_TEXT_ESCAPE_CHARS (backslash, backtick, asterisk, underscore, pipe, angles). Role bodies use RST_ROLE_BODY_ESCAPE_CHARS (backslash, backtick only). Performance Uses compiled regex patterns for efficient token and markup boundary detection.
«Function»	resolve_markup

9.1.1.3. Function build_sphinx_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes( ctx: context obj: object doc: mod_docitem.docitem_docstring_base ) -> List[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must convert a parsed Waterloo docstring into docutils nodes for Sphinx output. Must honor the current Waterloo scope before rendering the documented object. Must return an empty node list if the documented object is outside the current scope and scope-filter placeholders are disabled. Must render a note-style placeholder if the documented object is outside the current scope and scope-filter placeholders are enabled. Must assign a deterministic anchor id to the documentation box. Must register the anchor id for cross-document Waterloo references. Must render the docstring as a two-column documentation box with section labels on the left and rendered section content on the right. Must add a signature row for callable objects. Must preserve section-specific structure, for example executable-contract bullet lists, free-form paragraphs, grouped definitions, and public-object lists. Must resolve selected reference-like entries as internal links where targets can be resolved. Must mark resolvable but scope-filtered reference targets as out-of-scope entries. Must keep unresolved reference entries visible as role-rendered fallback text. Must emit runtime warnings for unresolved entries in sections where linkability is expected. Must not raise hard validation errors for unresolved references; semantic enforcement belongs to the validator.
Parameters	ctx Rendering context providing Sphinx state, configuration, inline parsing, and Waterloo role helpers. obj The documented Python object. doc Parsed Waterloo docstring tree for obj.
Returns	List of docutils.nodes.Node representing the rendered documentation box or scope-filter placeholder.
Raises	NotImplementedError May raise if the docstring contains a section shape that is not supported by this renderer. RuntimeError May raise if unexpected section structure is encountered. ValueError May raise if free-form itemization starts with an invalid nested list structure. RuntimeWarning May emit warnings for unresolved link targets (for example in Public_*, Derived_from, or normative See_also).
Notes	Usage This function is typically not called directly. It is called by the various autodoc functions. Scope filtering Scope filtering is handled before the documentation box is built. When placeholders are enabled, skipped objects remain visible in the rendered document as lightweight notes. Linking Internal links are created using anchor ids from build_anchor and the Sphinx environment’s Waterloo anchor index. Built-in exceptions in section Raises are intentionally rendered as plain text without internal links. Last reviewed 2026-07-23
«Function»	build_sphinx_nodes

9.1.1.4. Function build_sphinx_nodes_full

Signature	sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes_full( ctx: context class_obj: Any session: mod_docitem.DocSession ) -> List[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must parse and validate the Waterloo docstring of class_obj. Must validate the class method coverage declared by the class docstring. Must return an empty node list if the class docstring is outside the current Waterloo scope. Must render the class docstring with build_sphinx_nodes. Must recursively render nested classes listed in Public_classes if they exist on class_obj. Must render public methods listed in Public_methods if they exist, resolve to function objects, have docstrings, validate successfully, and are visible in the current Waterloo scope. Must insert method block prolog nodes before rendered public methods. Must render documented property accessor methods for property entries listed in Public_variables. Must reuse session for parsing and validation work performed during the recursive render pass. May skip listed members that cannot be found, cannot be represented as function objects, or do not have docstrings.
Parameters	ctx Rendering context providing Sphinx state, configuration, diagnostics, inline parsing, and Waterloo role helpers. class_obj The class object to render. session Session object used for parser and validator state shared across the recursive render pass.
Returns	List of docutils.nodes.Node representing the class, nested classes, public methods, and documented property accessors.
Raises	RuntimeError Must raise if class_obj has no docstring. May raise if parsing or validation of the class docstring fails. May raise if rendering the class docstring fails. NotImplementedError May forward unsupported section-shape errors from build_sphinx_nodes. ValueError May forward free-form itemization errors from build_sphinx_nodes. BaseException May forward exceptions from Sphinx or the Waterloo parser/validator.
Notes	Member errors The current method-rendering branch is intentionally tolerant and may skip problematic methods instead of aborting the complete class rendering pass. Scope filtering Unlike build_sphinx_nodes, this helper currently omits an out-of-scope class without rendering a placeholder. Last reviewed 2026-07-23
«Function»	build_sphinx_nodes_full

9.1.1.5. Function parse_inline

Signature	sphinxcontrib.waterloo_docstrings.wtrl_parse.parse_inline( inliner: InlinerProtocol parent: nodes.Element ln: int txt: str ) -> List[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must parse inline reStructuredText content and preserve warning and error messages. Must append all generated messages to the parent element as child nodes. Must return all parsed content nodes without discarding messages.
Description	This function wraps inliner.parse() to ensure that any warning or error messages generated during the parsing process are captured and added to the document tree instead of being silently discarded.
Parameters	inliner An inline element parser implementing InlinerProtocol. Must have a parse method and a document attribute with settings and reporter attributes. parent The parent Element to which parsed content and messages will be appended. ln The line number (integer) where the txt input begins in the source document. txt The reStructuredText source string (str) to be parsed for inline markup.
Returns	List of parsed docutils.nodes.Node instances representing the content found in txt. The returned list is created from the parse output; warning and error messages are appended directly to parent and not returned as part of the list.
Raises	Exception No exceptions are raised under normal conditions. Exceptions from underlying RST parsing or document handling may propagate depending on the inliner implementation.
Notes	Key difference from direct inliner.parse() calls This function always preserves document messages in the tree. Direct calls to inliner.parse() may discard messages, leading to silent data loss in warnings and error conditions.
«Function»	parse_inline

9.1.1.6. Class context

Preamble	normative sections Contract, Factory, Public methods scope extension
Contract	general Must provide the shared rendering state used by Waterloo Sphinx node builders. Must store the Docutils/Sphinx inline parser callback used to turn resolved Waterloo markup into nodes. Must store the source line number used for diagnostics and inline parsing. Must provide slots for the active Sphinx environment and configuration object. Must provide a cache for validated Waterloo docstrings used by scope-aware link rendering. Must provide a tracer for diagnostics emitted while resolving or rendering Waterloo content. Must provide configurable prolog hook callables for method overview and method block rendering. Must provide access to Waterloo role helper functions through context_roles. Must provide a method for applying hook configuration from a simple dictionary. constructor Must accept a callable for parsing inline text into a list of nodes.Node objects. Must accept a line number for error reporting. Must initialize env and config as unset placeholders. Must initialize default prolog hook callables. Must initialize an empty validated-docstring cache and a fresh tracer.
Factory	make_context Must create a context instance from a Sphinx application object, an inline parser callable, and a line number.
Public methods	__init__, set_build_prolog_method_overview, set_build_prolog_method_block, apply_config
Notes	Context population Call make_context instead of instantiating this class directly when Sphinx environment and configuration access are needed. Last reviewed 2026-07-23 Todo Methods like build_prolog_method_overview and build_prolog_method_block need to be reviewed.
«Class»	context

Signature	sphinxcontrib.waterloo_docstrings.wtrl_context.context.__init__( parse_inline: Callable[[nodes.Element, int, str], List[nodes.Node]] lineno: int ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must initialize the context with the given inline parser and line number. Must initialize the Sphinx environment env and configuration config placeholders as unset. Must initialize the validated-docstring cache wtrl_validated_doc_cache and tracer tr.
Parameters	parse_inline A callable that takes a nodes.Element parent, an integer line number, and a string of inline text, and returns a list of nodes.Node objects. lineno An integer line number within the source file.
Returns	None
Raises	<empty>
«Method»	context.__init__

Signature	sphinxcontrib.waterloo_docstrings.wtrl_context.make_context( app: SphinxAppProtocol | Any parse_inline: Callable[[nodes.Element, int, str], List[nodes.Node]] lineno: int ) -> context
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must create a context instance from a Sphinx application object, an inline parser callable, and a line number. Must extract the Sphinx environment and configuration from the application object and store them in the context. Must look for a docitem_context_configurator dictionary in the application object or the Sphinx environment. Must apply the configurator to the context if it is found.
Parameters	app A Sphinx application object. parse_inline A callable that takes a nodes.Element parent, an integer line number, and a string of inline text, and returns a list of nodes.Node objects. lineno An integer line number within the source file.
Returns	A context instance with the Sphinx environment, configuration, and optional configurator applied.
Raises	<empty>
Notes	Last reviewed 2026-07-23 Purpose This factory function provides a convenient way to create a fully initialized rendering context with Sphinx environment and configuration details extracted from the application object. It also searches for and applies optional context configurators, allowing extensible customization of rendering behavior without modifying the context initialization logic directly. Called whenever rendering content into the final document (e.g., HTML) at a specific source location (lineno).
«Function»	make_context

9.1.2. Directives for docstring rendering

Signature	sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_module_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must create a Waterloo rendering context for the active Sphinx application and source line. Must resolve the dotted module name qname to a Python module object, taking the current Waterloo module state into account. Must return diagnostic nodes if qname cannot be resolved. Must return diagnostic nodes if qname does not resolve to a module. Must return diagnostic nodes if the resolved module has no non-empty docstring. Must parse and validate the module’s Waterloo docstring. Must return structured tracer diagnostic nodes if parsing or validation fails. Must render the parsed docstring with build_sphinx_nodes.
Description	Implementation of directive .. wtrl_autodoc_module::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified module name to build nodes for.
Returns	List of generated docutils.nodes.Node representing the module documentation or a diagnostic replacement.
Raises	BaseException May forward unexpected exceptions from context creation, inline parsing, or build_sphinx_nodes.
Notes	Diagnostics Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors. Last reviewed 2026-07-23
«Function»	wtrl_build_autodoc_module_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must create a Waterloo rendering context for the active Sphinx application and source line. Must resolve the dotted class name qname to a class, taking the current Waterloo module/class state into account. Must return diagnostic nodes if qname cannot be resolved. Must return diagnostic nodes if qname does not resolve to a class. Must return diagnostic nodes if the resolved class has no non-empty docstring. Must parse and validate the class’ Waterloo docstring. Must return structured tracer diagnostic nodes if parsing or validation fails. Must render the parsed docstring with build_sphinx_nodes.
Description	Implementation of directive .. wtrl_autodoc_class::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified class name to document.
Returns	List of generated docutils.nodes.Node representing the class documentation or a diagnostic replacement.
Raises	BaseException May forward unexpected exceptions from context creation, inline parsing, or build_sphinx_nodes.
Notes	Diagnostics Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors. Last reviewed 2026-07-23
«Function»	wtrl_build_autodoc_class_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_function_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must create a Waterloo rendering context for the active Sphinx application and source line. Must resolve the dotted function name qname to a callable, taking the current Waterloo module/class state into account. Must return diagnostic nodes if qname cannot be resolved. Must return diagnostic nodes if qname does not resolve to a callable. Must return diagnostic nodes if the resolved callable has no non-empty docstring. Must parse and validate the function’s Waterloo docstring. Must return structured tracer diagnostic nodes if parsing or validation fails. Must render function and method profiles as method docstrings. Must render all other accepted callable profiles as inherited-method docstrings. Must render the parsed docstring with build_sphinx_nodes.
Description	Implementation of directive .. wtrl_autodoc_function::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified function name to document.
Returns	List of generated docutils.nodes.Node representing the callable documentation or a diagnostic replacement.
Raises	BaseException May forward unexpected exceptions from context creation, inline parsing, or build_sphinx_nodes.
Notes	Diagnostics Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors. Last reviewed 2026-07-23
«Function»	wtrl_build_autodoc_function_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_full_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must create a Waterloo rendering context for the active Sphinx application and source line. Must resolve the dotted class name qname to a class, taking the current Waterloo module/class state into account. Must return diagnostic nodes if qname cannot be resolved. Must return diagnostic nodes if qname does not resolve to a class. Must return diagnostic nodes if the resolved class has no non-empty docstring. Must delegate recursive class, nested-class, method, and property-accessor rendering to build_sphinx_nodes_full. Must return runtime diagnostic nodes if build_sphinx_nodes_full raises RuntimeError. Must return structured tracer diagnostic nodes if recursive rendering fails with another expected exception.
Description	Implementation of directive .. wtrl_autodoc_class_full::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified name of the class to be documented.
Returns	List of generated docutils.nodes.Node representing the recursively rendered class documentation or a diagnostic replacement.
Raises	BaseException May forward unexpected exceptions from context creation, inline parsing, or diagnostic rendering.
Notes	Diagnostics Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors. Recursion The traversal policy is implemented by build_sphinx_nodes_full; this directive wrapper only resolves the top-level class and translates failures into Sphinx nodes. Last reviewed 2026-07-23
«Function»	wtrl_build_autodoc_class_full_nodes

9.1.3. Directives for controlling the state stack

9.1.3.1. Scope stack

Signature	sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_scope_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int scope_tag: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must push the scope identifier in scope_tag to the scope stack, which makes it the new current scope. Must build a list of Docutils nodes which represent a message about the changed state in the document. May write a log message to stdout.
Description	Implementation of directive .. wtrl_push_current_scope::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. scope_tag The scope identifier to push onto the stack.
Returns	The list of generated docutils.nodes.Node describing the resulting default scope state.
Raises	RuntimeError Must raise if scope_tag is unknown. BaseException May propagate exceptions from within Sphinx or Docutils.
See also	wtrl_build_pop_current_scope_nodes, wtrl_build_push_current_module_nodes, wtrl_build_push_current_class_nodes
Notes	Last reviewed 2026-07-16
«Function»	wtrl_build_push_current_scope_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_scope_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int scope_tag: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must compare the scope identifier name in qname to the top of the scope stack and raise an exception in case of mismatch. Must pop one element from the scope stack. Must build a list of Docutils nodes which represent a message about the changed state in the document. May write a log message to stdout.
Description	Implementation of directive .. wtrl_pop_current_scope::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. scope_tag The scope identifier to compare and pop from the stack.
Returns	The list of generated docutils.nodes.Node describing the resulting default scope state.
Raises	RuntimeError Must raise on the attempt to access an element from an empty stack. Must raise if the scope identifier on top of the stack does not match scope_tag. Must raise if scope_tag is unknown or mismatches the stack top. BaseException May propagate exceptions from within Sphinx or Docutils.
Notes	Last reviewed 2026-07-16
See also	wtrl_build_push_current_scope_nodes, wtrl_build_pop_current_module_nodes, wtrl_build_pop_current_class_nodes
«Function»	wtrl_build_pop_current_scope_nodes

9.1.3.2. Module stack

Signature	sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_module_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must push the qualified module name in text to the module stack, which makes it the new current module. Must resolve qname. Must build a list of Docutils nodes which represent a message about the changed state in the document. May write a log message to stdout.
Description	Implementation of directive .. wtrl_push_current_module::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified module name to push onto the stack.
Returns	The list of generated docutils.nodes.Node describing the resulting default module state.
Raises	RuntimeError Must raise if qname does not resolve to a module. BaseException May propagate exceptions from resolve_qualified_name. May propagate exceptions from within Sphinx or Docutils.
See also	wtrl_build_pop_current_module_nodes, wtrl_build_push_current_class_nodes, wtrl_build_push_current_scope_nodes
Notes	Last reviewed 2026-07-16
«Function»	wtrl_build_push_current_module_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_module_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must compare the qualified module name in qname to the top of the module stack and raise an exception in case of mismatch. Must resolve qname against the current module/class context. Must pop one element from the module stack. Must build a list of Docutils nodes which represent a message about the changed state in the document. May write a log message to stdout.
Description	Implementation of directive .. wtrl_pop_current_module::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified module name to compare and pop from the stack.
Returns	The list of generated docutils.nodes.Node describing the resulting default module state.
Raises	RuntimeError Must raise on the attempt to access an element from an empty stack. Must raise if the qualified name on top of the stack does not match qname. Must raise if qname does not resolve to a module. BaseException May propagate exceptions from resolve_qualified_name. May propagate exceptions from within Sphinx or Docutils.
See also	wtrl_build_push_current_module_nodes, wtrl_build_pop_current_class_nodes, wtrl_build_pop_current_scope_nodes
Notes	Last reviewed 2026-07-16
«Function»	wtrl_build_pop_current_module_nodes

9.1.3.3. Class stack

Signature	sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_class_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must push the qualified class name in text to the class stack, which makes it the new current class. Must resolve qname. Must build a list of Docutils nodes which represent a message about the changed state in the document. May write a log message to stdout.
Description	Implementation of directive .. wtrl_push_current_class::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified class name to push onto the stack.
Returns	The list of generated docutils.nodes.Node describing the resulting default module state.
Raises	RuntimeError Must raise if qname does not resolve to a class. BaseException May propagate exceptions from resolve_qualified_name. May propagate exceptions from within Sphinx or Docutils.
See also	wtrl_build_pop_current_class_nodes, wtrl_build_push_current_module_nodes, wtrl_build_push_current_scope_nodes
Notes	Last reviewed 2026-07-16
«Function»	wtrl_build_push_current_class_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_class_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must compare the qualified class name in qname to the top of the class stack and raise an exception in case of mismatch. Must resolve qname against the current module/class context. Must pop one element from the class stack. Must build a list of Docutils nodes which represent a message about the changed state in the document. May write a log message to stdout.
Description	Implementation of directive .. wtrl_pop_current_class::.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname The qualified class name to compare and pop from the stack.
Returns	The list of generated docutils.nodes.Node describing the resulting default class state.
Raises	RuntimeError Must raise on the attempt to access an element from an empty stack. Must raise if the qualified name on top of the stack does not match qname. Must raise if qname does not resolve to a class. BaseException May propagate exceptions from resolve_qualified_name. May propagate exceptions from within Sphinx or Docutils.
See also	wtrl_build_push_current_class_nodes, wtrl_build_pop_current_module_nodes, wtrl_build_pop_current_scope_nodes
Notes	Last reviewed 2026-07-16
«Function»	wtrl_build_pop_current_class_nodes

9.1.4. Directives for rendering signatures

9.1.4.1. Function wtrl_build_method_signature_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must create a list of docutil-nodes representing the method signature as inline text.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname Qualified name of method to render.
Returns	The list of generated docutils.nodes.Node describing the method signature.
Raises	BaseException May propagate exceptions from docutils.
See also	wtrl_build_function_signature_nodes, wtrl_build_method_signature_block_nodes
Notes	Last reviewed 2026-07-23
«Function»	wtrl_build_method_signature_nodes

9.1.4.2. Function wtrl_build_function_signature_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must create a list of docutil-nodes representing the function signature as inline text.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname Qualified name of function to render.
Returns	The list of generated docutils.nodes.Node describing the function signature.
Raises	BaseException May propagate exceptions from docutils.
See also	wtrl_build_method_signature_nodes, wtrl_build_function_signature_block_nodes
Notes	Last reviewed 2026-07-23
«Function»	wtrl_build_function_signature_nodes

9.1.4.3. Function wtrl_build_method_signature_block_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_block_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must create a list of docutil-nodes representing the method signature as paragraph with one parameter per line.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname Qualified name of method to render.
Returns	The list of generated docutils.nodes.Node describing the method signature.
Raises	BaseException May propagate exceptions from docutils.
See also	wtrl_build_method_signature_nodes, wtrl_build_function_signature_block_nodes
Notes	Last reviewed 2026-07-23
«Function»	wtrl_build_method_signature_block_nodes

9.1.4.4. Function wtrl_build_function_signature_block_nodes

Signature	sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_block_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must create a list of docutil-nodes representing the function signature as paragraph with one parameter per line.
Parameters	app The Sphinx application instance that carries configuration and environment state. inliner The Docutils inliner used to parse inline markup into nodes. lineno Line number in the source document. qname Qualified name of function to render.
Returns	The list of generated docutils.nodes.Node describing the function signature.
Raises	BaseException May propagate exceptions from docutils.
See also	wtrl_build_method_signature_block_nodes, wtrl_build_function_signature_nodes
Notes	Last reviewed 2026-07-23
«Function»	wtrl_build_function_signature_block_nodes

9.1.5. Roles for semantic markup

9.1.5.1. Helper classes

Preamble	normative sections Contract scope extension
Contract	general Must be a frozen dataclass that aggregates the parameters passed to Docutils role handler functions. constructor Default
«Class»	RolePara

9.1.5.2. Function wtrl_attr_role

Signature	sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_attr_role( para: RolePara ) -> RoleResult
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must create a docutils.nodes.literal node with the text in para.text and the CSS class wtrl_attr. Must return the created node as the only generated document node. Must return an empty list of system messages.
Parameters	para RolePara instance containing the normalized Docutils role parameters.
Returns	A RoleResult containing a one-element node list and an empty system-message list.
Raises	BaseException May propagate exceptions from docutils.
See also	RolePara, RoleResult
Notes	Representative role This docstring documents the common implementation pattern used by the simple Waterloo roles in this module. Most of these roles create either one docutils.nodes.literal node or one docutils.nodes.inline node, attach a semantic CSS class, and return no system messages. Node kind Object-like roles such as wtrl_attr, wtrl_func, and wtrl_type use literal nodes. Text-semantic roles such as wtrl_dfn, wtrl_label, wtrl_norm, and wtrl_term use inline nodes. Examples my_attribute JSON-like text: { “my_attribute”: “my_value” } Last reviewed 2026-07-23
«Function»	wtrl_attr_role

9.1.5.3. Similar roles

There are around 15 more role implementations like wtrl_attr_role. They differ only in the CSS class passed and in the docutils node classes literal versus inline. We omit them here to keep the document low in redundancy.

9.1.5.4. Function wtrl_var_type_role

Signature	sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_var_type_role( para: RolePara ) -> RoleResult
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope extension
Contract	general Must parse the text in para.text as a variable name and type separated by the first colon. Must strip surrounding whitespace from the parsed variable name and type. Must return a Docutils error system message if para.text does not contain a colon. Must return a Docutils error system message if either the parsed variable name or type is empty. Must create a wrapper docutils.nodes.inline node with CSS class wtrl_var_type for valid input. Must add the variable name as a child inline node with CSS class wtrl_var. Must add a colon as a child inline node with CSS class wtrl_op. Must add the type as a child inline node with CSS class wtrl_type.
Parameters	para RolePara instance containing the normalized Docutils role parameters.
Returns	On valid input, a RoleResult containing one wrapper node and an empty system-message list. On invalid input, a RoleResult containing no document nodes and one Docutils error system message.
Raises	BaseException May propagate unexpected exceptions from docutils.
See also	RolePara, RoleResult
Notes	Structure This role is intentionally different from the simple Waterloo roles because it exposes the variable name, separator, and type as separately styleable inline nodes. Separator Only the first colon separates variable and type. Additional colons remain part of the type text. Examples n: int q: float para: RolePara result: tuple[List[nodes.Node], list[nodes.Node]] Last reviewed 2026-07-23
«Function»	wtrl_var_type_role

The code for the following state change is:

.. wtrl_pop_current_module:: sphinxcontrib.waterloo_docstrings.extension

Waterloo module context

Default module qualifier sphinxcontrib.waterloo_docstrings.extension ends here. New default: sphinxcontrib.waterloo_docstrings.

The code for the following state change is

.. wtrl_pop_current_module:: sphinxcontrib.waterloo_docstrings

Waterloo module context

Default module qualifier sphinxcontrib.waterloo_docstrings ends here. New default: doc_errors.

The code for the following state change is

.. wtrl_pop_current_scope:: core

Waterloo scope context

Scope qualifier core ends here. New current scope: public.