11. Reference - Rendering Showcase

This chapter is primarily a reference showcase for the Sphinx rendering layer. The Waterloo project itself is best understood as a toolkit consisting of waterlint, the Pygments lexer, the MCP server, and the VSCode extension.

Most users will not import the internal docitem*.py modules directly in their own projects. Those modules are implementation details of the toolkit and are documented here mainly so the rendered API can be inspected in a structured form.

Scope below this point is set to core.

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

11.1. Module docitem

Preamble	normative sections Contract, Definitions, Public classes, Public functions, Public types, Public constants
Contract	general Must provide node classes and parsing/validation utilities for Waterloo docstrings. In detail: Must provide a node class for each type of section and subsection in a Waterloo docstring. Must provide an appropriate base class hierarchy with a single base class as root of this hierarchy. Must be able to represent any valid docstring by a single node which is the root of a tree of nodes. Must provide validator functions for docstrings for modules, classes and callables. Must provide functions for verifying coverage where applicable.
Definitions	Identifier A string that matches the regular expression RE_IDENTIFIER (see Public_constants). Qualified_Identifier A string that matches the regular expression RE_QUALIFIED_IDENTIFIER (see Public_constants).
Public functions	is_obj_module, is_obj_class, is_obj_function, is_obj_method_like, is_attr_annotated, is_attr_final, get_obj_name, get_obj_path, get_obj_annotations, resolve_object, get_status, get_profile, get_num_indent, parse_indent_docstring, get_tree_of_section, get_tree_of_subsection, get_scopes_of_tree_var, to_string_tree, validate_docstring_method, validate_docstring_inherited_method, validate_docstring_class, validate_docstring_module, validate_docstring, validate_class_class_coverage, validate_class_method_coverage, validate_class_constant_coverage, validate_class_variable_coverage, validate_class_coverage, validate_module_class_coverage, validate_module_function_coverage, validate_module_type_coverage, validate_module_constant_coverage, validate_module_variable_coverage, validate_module_coverage, gen_documentable_objects, make_docitem_tree
Function overview	is_attr_annotated Find out if an attribute of a class or module is annotated. is_attr_final Find out if an attribute of a class or module is annotated as ‘Final’. resolve_object Resolve an object by its Qualified_Identifier get_status Extract documented object status from docitem tree get_profile Extract documented profile from docitem tree get_num_indent Count number of leading indent units of a string. parse_indent_docstring The fundamental parsing function which creates docstring trees from Waterloo docstrings. get_tree_of_section Get tree assigned to a section label from a docstring tree. get_tree_of_subsection Get tree assigned to a subsection label from a docstring tree. get_scopes_of_tree_var Get scopes and explicit-scope flag from a docstring tree. to_string_tree Render docstring to string validate_docstring_method Validator for method and function docstrings validate_docstring_inherited_method Validator for inherited method docstrings validate_docstring_class Validator for class docstrings validate_docstring_module Validator for module docstrings validate_docstring Validator for docstrings for generic objects. validate_class_class_coverage Validate mutual coverage of nested classes and class docstring entries. validate_class_method_coverage Validate mutual coverage of methods and class docstring entries. validate_class_constant_coverage Verify constant existence and ‘Final’ annotation. validate_class_variable_coverage Verify variable existence. validate_class_coverage Verify existence (and mutual coverage were applicable) of methods mentioned in the class docstring. validate_module_class_coverage Validate mutual coverage of classes and module docstring entries. validate_module_function_coverage Validate mutual coverage of functions and module docstring entries. validate_module_type_coverage Verify existence of types mentioned in the module docstring. validate_module_constant_coverage Verify constant existence and ‘Final’ annotation. validate_module_variable_coverage Verify variable existence. validate_module_coverage Verify existence (and mutual coverage were applicable) of classes, functions, types, constants mentioned in the module docstring. gen_documentable_objects Iterate over objects which may have a docstring. make_docitem_tree Generate a docitem tree from a docstring.
Public classes	tracer, docitem_base, docitem_list_base, docitem_map_base, docitem_free_text_entry_base, docitem_list_of_symbols_base, docitem_profile, docitem_normative_sections, docitem_status, docitem_preamble, docitem_constructor, docitem_general, docitem_invariants, docitem_requires, docitem_ensures, docitem_base_to_inherit_from, docitem_traits, docitem_contract_module, docitem_contract_class, docitem_contract_method, docitem_contract_inherited_method, docitem_derived_from, docitem_factory_functions, docitem_factory, docitem_class_overview_entry, docitem_class_overview, docitem_public_types_entry, docitem_public_types, docitem_public_assignables_entry, docitem_public_assignables_base, docitem_method_overview_entry, docitem_method_overview, docitem_function_overview_entry, docitem_function_overview, docitem_returns, docitem_parameters_entry, docitem_parameters, docitem_raises_entry, docitem_raises, docitem_definitions_entry, docitem_definitions, docitem_terminology_entry, docitem_terminology, docitem_notes_entry, docitem_notes, docitem_description, docitem_see_also, docitem_docstring_base, docitem_docstring_module, docitem_docstring_class, docitem_docstring_method, docitem_docstring_inherited_method, Scope, Flavour, Format, Status
Class overview	tracer Context and helper for exceptions and warnings. docitem_base The base class for all docitem classes which form the docstring tree. docitem_list_base The base class for docitem classes managing a list of strings. docitem_map_base The base class for docitem classes managing a map from strings to docitem nodes docitem_free_text_entry_base The base class for nodes which consist of free-text string. docitem_list_of_symbols_base The base class for nodes which contein a list of identifiers. docitem_profile Node class for section profile docitem_normative_sections Node class for subsection normative_sections docitem_status Node class for subsection status docitem_preamble Node class for section Preamble docitem_constructor Node class for subsection constructor docitem_general Node class for subsection general docitem_invariants Node class for subsection invariants docitem_requires Node class for subsection requires docitem_ensures Node class for subsection ensures docitem_base_to_inherit_from Node class for subsection base docitem_traits Node class for subsection traits docitem_contract_module Node class for section Contract, profile module. docitem_contract_class Node class for section Contract, profile class. docitem_contract_method Node class for section Contract, profile method or function. docitem_contract_inherited_method Node class for section Contract, profile inherited_method. docitem_derived_from Node class for section Derived_from. docitem_factory_functions Node class for entries in section Factory. docitem_factory Node class for section Factory. docitem_class_overview_entry Node class for entries in section Class_overview. docitem_class_overview Node class for section Class_overview. docitem_public_types_entry Node class for entries in section Public_types. docitem_public_types Node class for section Public_types. docitem_public_assignables_entry Node class for entries in section Public_constants and Public_variables. docitem_public_assignables_base Node base class for sections Public_constants and Public_variables. docitem_method_overview_entry Node class for entries in section Method_overview. docitem_method_overview Node class for section Method_overview. docitem_function_overview_entry Node class for entries in section Function_overview. docitem_function_overview Node class for section Function_overview. docitem_returns Node class for section Returns. docitem_parameters_entry Node class for a parameter description docitem_parameters Node class for section Parameters docitem_raises_entry Node class for entries in section Raises. docitem_raises Node class for section Raises docitem_definitions_entry Node class for entries in section Definitions. docitem_definitions Node class for section Definitions docitem_terminology_entry Node class for entries in section Terminology. docitem_terminology Node class for section Terminology docitem_notes_entry Node class for entries in section Notes. docitem_notes Node class for section Notes docitem_description Node class for section Description. docitem_see_also Node class for section See_also docitem_docstring_base Base class for docstring nodes docitem_docstring_module Node class for a module docstring docitem_docstring_class Node class for a class docstring docitem_docstring_method Node class for a function or method docstring docitem_docstring_inherited_method Node class for an inherited method docstring
Public types	DocstringTree The type alias for docstring trees. Documentable Type for objects that can have a docstring. Profile The string literals representing values in the Preamble.profile subsection. Scopes Type alias for a set of scopes.
Public constants	RE_IDENTIFIER Regular expression for identifiers: [A-Za-z_][A-Za-z0-9_]* RE_QUALIFIED_IDENTIFIER Regular expression for qualified identifiers: [A-Za-z_][A-Za-z0-9_]*([.][A-Za-z_][A-Za-z0-9_]*)* KEYWORDS_OF_NORMATIVITY The set of normative keywords. CANONICAL_ORDER_OF_SECTIONS A canonical order for sections and subsection in order to reduce permutative noise for LLMs. SCOPE_TAG_MAP Map string representations of scopes to symbolic/numeric values. FLAVOUR_TAG_MAP Map string representations of flavours to symbolic/numeric values. FORMAT_TAG_MAP Map string representations of output formats to symbolic/numeric values. STATUS_TAG_MAP Map string representations of Contract.status values to symbolic values.
Module	sdv.doc.waterloo.docitem

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

11.1.1. Fundamental helpers

11.1.1.1. get_obj_name

Signature	sdv.doc.waterloo.docitem_helper.get_obj_name( obj: object ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope public
Contract	general Must employ reasonable heuristics to extract a representative name. Must return string objects as-is. Must prioritize __qualname__ over __name__ for types/functions. Must resolve to the name of the underlying class for object instances. Must provide the string representation as a terminal fallback.
Parameters	obj The object to inspect.
Returns	The resolved name according to the defined hierarchy.
Raises	<empty>
Notes	Last review 2026-06-22 Limitations This helper is best-effort and object-local. It does not reconstruct containment context for nested instances. Behavior for property-like descriptors such as property and cached_property is undefined. If you need a more precise identifier, prefer get_obj_fully_qualified_name.
See also	get_obj_fully_qualified_name
Function	get_obj_name

11.1.1.2. get_obj_fully_qualified_name

Signature	sdv.doc.waterloo.docitem_helper.get_obj_fully_qualified_name( obj: object ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises scope public
Contract	general Must return a fully qualified object name where possible. Must return module objects as their module name. Must return callable/class/object names as <module> . <qualname> when both parts are available. Must fall back to get_obj_name if no module prefix can be determined. Must return input strings unchanged. Must resolve class instances to their class name, prefixed by the module name when available.
Parameters	obj The object to inspect.
Returns	Best-effort fully qualified object name.
Raises	<empty>
Notes	Last review 2026-06-23 Limitations Behavior for property-like descriptors such as property and cached_property is undefined.
Function	get_obj_fully_qualified_name

11.1.1.3. get_obj_path

Signature	sdv.doc.waterloo.docitem_helper.get_obj_path( obj: object ) -> str | None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must return an absolute filesystem path to the module that defines obj, if determinable. Must return None if the path cannot be determined (e.g. builtins, C-extensions, interactive objects).
Parameters	obj The object whose defining module path is requested.
Returns	Absolute path string or None.
Raises	<empty>
Notes	Last review 2026-02-05
Function	get_obj_path

11.1.1.4. get_obj_docstring

Signature	sdv.doc.waterloo.docitem_helper.get_obj_docstring( obj: object ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must return the best available docstring text for obj. Must prefer the raw source docstring obtained by get_source_docstring. Must support modules, classes, functions/methods, descriptors (staticmethod, classmethod, property / cached_property), partial/partialmethod objects, and callable instances via __call__. Must follow __wrapped__ chains created by functools.wraps. Must return the empty string if no docstring is available.
Parameters	obj Any python object that might carry a docstring.
Returns	Must return the best available docstring text, or the empty string if none exists.
Raises	<empty>
Notes	Last review 2026-05-15 General The object-level cache avoids repeating the wrapper walk for the same object.
Function	get_obj_docstring

11.1.1.5. get_obj_annotations

Signature	sdv.doc.waterloo.docitem_helper.get_obj_annotations( obj: object ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build a dict (the result) as follows: Must analyse the object’s annotations by means of inspect. On success, must add the annotations to the result. Must check for an attribute __type_params__ in the object. If it exists (as of Python 3.12), must iterate over the tuple obj.__type_params__ and add pairs consisting of param.__name__ and type(param) to the result.
Parameters	obj The object to be inspected.
Returns	A dict representing the object’s annotations.
Raises	BaseException May propagate exceptions other than TypeError and ValueError from module inspect.
Notes	Result The returned object mostly results from inspect.get_annotations, but may be extended with type parameters for Python 3.12+.
Function	get_obj_annotations

11.1.1.6. is_obj_module

Signature	sdv.doc.waterloo.docitem_helper.is_obj_module( obj: object ) -> TypeIs[ModuleType]
Preamble	normative sections Contract, Parameters, Returns, Raises scope public
Contract	general Must relay to inspect.ismodule
Parameters	obj The object to inspect.
Returns	True if obj is a module.
Raises	BaseException May propagate exceptions from inspect.
Notes	Purpose Uniform wrapper, allows us to add debugging output or hooks in case of trouble.
Function	is_obj_module

11.1.1.7. is_obj_class

Signature	sdv.doc.waterloo.docitem_helper.is_obj_class( obj: object ) -> TypeIs[type[object]]
Preamble	normative sections Contract, Parameters, Returns, Raises scope public
Contract	general Must relay to inspect.isclass
Parameters	obj The object to inspect.
Returns	True if obj is a class.
Raises	BaseException May propagate exceptions from inspect.
Notes	Purpose Uniform wrapper, allows us to add debugging output or hooks in case of trouble.
Function	is_obj_class

11.1.1.8. is_obj_function

Signature	sdv.doc.waterloo.docitem_helper.is_obj_function( obj: object ) -> TypeIs[Callable[…, Any]]
Preamble	normative sections Contract, Parameters, Returns, Raises scope public
Contract	general Must relay to inspect.isroutine
Parameters	obj The object to inspect.
Returns	True if obj is a routine, which is a pretty general concept for “something that can be called”, but excludes callable classes.
Raises	BaseException May propagate exceptions from inspect.
Notes	Purpose Uniform wrapper, allows us to add debugging output or hooks in case of trouble.
Function	is_obj_function

11.1.1.9. is_obj_method_like

Signature	sdv.doc.waterloo.docitem_helper.is_obj_method_like( obj: object ) -> TypeIs[Callable[…, Any]]
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must detect callables which should be treated as “method-like” for Waterloo profile heuristics. Must return False for non-routines. Must treat callables with class-like __qualname__ (A.f) as method-like. Should additionally use decorators @staticmethod, @classmethod, @abstractmethod, @abc.abstractmethod as hints.
Parameters	obj Object to inspect.
Returns	True if obj is callable and method-like by heuristic.
Raises	<empty>
Function	is_obj_method_like

11.1.1.10. is_obj_documentable

Signature	sdv.doc.waterloo.docitem_helper.is_obj_documentable( obj: object ) -> TypeIs[Documentable]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must find out if the object passed can have a docstring.
Parameters	obj The object to examine.
Returns	True if obj is a module, class or function, else False.
Raises	<empty>
Notes	Last review 2026-06-22 Documentable vs. non-documentable objects Only modules, classes, and functions are considered documentable for Waterloo docstring generation and validation. Accordingly, sections like Public_types, Public_constants, and Public_variables in module and class docstrings document named values that are not documentable objects themselves.
Function	is_obj_documentable

11.1.1.11. is_obj_named_value

Signature	sdv.doc.waterloo.docitem_helper.is_obj_named_value( obj: object ) -> TypeIs[Callable[…, Any]]
Preamble	normative sections Contract, Parameters, Returns, Raises scope public
Contract	general Must be equivalent to not is_obj_module and not is_obj_class and not is_obj_function. requires The caller must ensure that the object exists.
Parameters	obj The object to inspect.
Returns	True if obj is a named value
Raises	BaseException May propagate exceptions from inspect.
Notes	Purpose Uniform wrapper, allows us to add debugging output or hooks in case of trouble.
Function	is_obj_named_value

11.1.1.12. get_func_obj_from_callable

Signature	sdv.doc.waterloo.docitem_helper.get_func_obj_from_callable( obj: object ) -> Callable[…, Any] | None
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension status stable
Contract	general Must return the function object assigned to the object for a wide class of cases. Must handle functions in classes without decorators. Must handle functions in classes with decorator @staticmethod. Must handle functions in classes with decorator @classmethod. Must handle callable classes. Must handle instances of callable classes. Must handle functions at module level. Must handle generators. Should be able to handle built-ins.
Parameters	obj The object to analyze.
Returns	The function object (or built-in) assigned to obj.
Raises	<empty>
Notes	API The signature is stable, but we might add cases to the implementation.
Function	get_func_obj_from_callable

11.1.2. Typechecking helpers

11.1.2.1. is_attr_annotated

Signature	sdv.doc.waterloo.docitem_helper.is_attr_annotated( obj: AnnotatableObject attr: str ) -> bool
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must find out whether the requested name is annotated on the object.
Parameters	obj The annotatable object to inspect, for example a module, class, function, or method. attr The attribute or annotation name to be tested. For functions and methods this includes parameter names and the return annotation.
Returns	Must return True if the attribute is annotated, else False.
Raises	BaseException May propagate exceptions from getattr.
Notes	Last review 2026-02-04
Function	is_attr_annotated

11.1.2.2. is_attr_final

Signature	sdv.doc.waterloo.docitem_helper.is_attr_final( obj: AnnotatableObject attr: str ) -> bool
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must find out whether the attribute passed is annotated as Final.
Parameters	obj The class or module containing the attribute. attr The name of the attribute to be tested.
Returns	Must return True if the attribute is annotated as Final, else False.
Raises	BaseException May propagate exceptions from get_type_hints.
Notes	Last review 2026-02-04
Function	is_attr_final

11.1.3. Tokenizer functions

11.1.3.1. get_num_indent

Signature	sdv.doc.waterloo.docitem_tokenizer.get_num_indent( tr: tracer line: str indent_scheme: int ) -> int
Preamble	normative sections Definitions, Contract, Parameters, Returns, Raises status stable
Definitions	TAB A scheme that demands indentation by means of an integer number of tab characters (ASCII 0x09). For this scheme, INDENT_UNIT is a single tab character. SPC4 A scheme that demands indentation by means of an integer multiple of four space characters (ASCII 0x20). For this scheme, INDENT_UNIT consists of four space characters.
Contract	general Must accept a single line string and an indentation scheme. Must count the number of leading indentations of the input according to the scheme passed. Must accept an empty string.
Parameters	tr Tracer for better error messages line A single line string. indent_scheme A symbolic value representing one of the two possible indentation schemes TAB or SPC4.
Returns	Must return the number of indentations found at the beginning of the string in units as described by the indentation scheme passed.
Raises	RuntimeError Must raise if prefix contains a mix not representable as n repetitions of INDENT_UNIT. Must raise if the leading white space characters (tabs or four spaces) at the beginning of the line cannot be described by the indentation scheme passed.
Function	get_num_indent

11.1.3.2. parse_indent_docstring

Signature	sdv.doc.waterloo.docitem_tokenizer.parse_indent_docstring( tr: tracer text: str session: DocSession ) -> DocstringTree
Preamble	normative sections Definitions, Contract, Description, Parameters, Returns, Raises
Definitions	DocstringTree A value matching the following type: DocstringTree = List[ Union[ str, "DocstringTree"]]
Contract	general Must generate a DocstringTree from a docstring. In order to achieve this: Must accept a multiline string. Must remove empty lines at beginning and end of the input. Must insist on a uniform indentation scheme as definined normatively in get_num_indent. Must strip the indentation common to all lines if there is any, where common means: common to all only non-empty lines. Must iterate over the docstring’s lines and skip empty lines. Must return an empty list (= empty docstring tree) on empty input. Must maintain a state engine and update it on each incoming line.
Description	This section is normative. The state engine consists of the following components: 1. A DocstringTree (initial state: []), given by a variable target. 2. A stack the elements of which point to target or any subtree thereof (see recursive definition of DocstringTree; initial state is [target]), represented by a variable stack. 3. An integer variable cur_indent which represents the current level of indendation during line parsing. For each incoming line, processed sequentially, the following happens: If the indentation level remains unchanged, the line is appended to the substree represented by the top element of stack. If the indentation level increases, an empty DocstringTree is appended to the subtree referenced by the top element of stack and a reference to this DocstringTree is pushed to stack. If the indentation level decreases by n indentation units, an element is popped from stack for each of the n indentation levels.
Parameters	tr Tracer for better error messages text A multiline docstring with possibly indented lines. session A DocSession object for various caching tasks.
Returns	Must return the DocstringTree described as target in section Description in the state reached after parsing the entire input.
Raises	RuntimeError Must raise if indentation grows by more than 1 unit from one line to the next. Must raise if inconsistent indentation (tab vs space) is detected. May propagate exceptions from get_num_indent.
Function	parse_indent_docstring

11.1.3.3. resolve_object

Signature	sdv.doc.waterloo.docitem_validator.resolve_object( ref: str current_obj: object ) -> tuple[object, str]
Preamble	normative sections Definitions, Contract, Parameters, Returns, Raises
Definitions	Identifier A string matching the regular expression [a-zA-Z_][a-zA-Z0-9_]*. Qualified_Identifier A string formed by concatenating one or more Identifiers with “.” as separator. Public_object An object that is importable as a module attribute or as an attribute of an object reachable from an importable module. Resolved_reference A pair (obj, qname) where qname is a candidate reference string that was successfully resolved and obj is the resulting Python object.
Contract	general Must attempt to resolve ref (an Identifier or Qualified_Identifier) to an existing Public_object. Must return the first successfully resolved candidate together with the exact candidate string that succeeded. Must treat a ref containing “.” as already qualified and try it directly before any context-derived qualification. Must for an unqualified ref, construct resolution candidates from current_obj in the following order where applicable: Must (1) <module_of_current_obj>.<ref> if the module of current_obj can be determined, Must (2) <current_obj.__module__>.<current_obj.__qualname__>.<ref> if current_obj is a class, Must (3) <current_obj.__module__>.<enclosing_qualname_prefix>.<ref> if current_obj is a function nested in a qualname path, Must and finally (4) ref as last fallback. Must skip duplicate candidate strings while preserving the candidate order. Must resolve a candidate by importing the longest importable module prefix of the candidate and then applying getattr for each remaining “.”-separated attribute component. Must raise ImportError if none of the candidates can be resolved.
Parameters	ref Reference string to resolve. It may be an Identifier (unqualified) or a Qualified Identifier (contains “.”). current_obj Context object that determines which qualified candidates are tried for an unqualified ref.
Returns	Must return a Resolved_reference.
Raises	ImportError Must raise if ref cannot be resolved via any candidate derived from current_obj and the fallback candidate ref. Must raise if a candidate contains an attribute chain that cannot be traversed (missing attribute) or if no module prefix of the candidate can be imported. AssertionError Must relay from importlib while trying to import the resolved module. IndexError Must relay from importlib while trying to import the resolved module. NameError Must relay from importlib while trying to import the resolved module. NotImplementedError Must relay from importlib while trying to import the resolved module. PermissionError Must relay from importlib while trying to import the resolved module. SyntaxError Must relay from importlib while trying to import the resolved module.
Function	resolve_object

11.1.4. AST properties

11.1.4.1. get_status

Signature	sdv.doc.waterloo.docitem_validator.get_status( tr: tracer obj: object top: docitem_docstring_base ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises status experimental
Contract	general Must check for existence of a node docitem_status in the AST passed. If it exists, must return its string-valued content. If it does not exist, must return “stable”.
Parameters	tr Tracer obj The object to be inspected top The AST from parsing the object docstring.
Returns	The documented object status or its default.
Raises	<empty>
Notes	Status Function may be renamed soon.
Function	get_status

11.1.5. Per-object validators

11.1.5.1. validate_docstring_method

Signature	sdv.doc.waterloo.docitem_validator.validate_docstring_method( tr: tracer obj: Callable[…, Any] top: docitem_docstring_method node_contract: docitem_map_base node_normative_sections: docitem_list_base session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must validate the docitem tree top against the callable object obj. Must ensure that Contract contains a section general. Must ensure that all sections declared as normative exist. Must ensure that section Parameters exists. Must ensure that section Returns exists. Must ensure that section Raises exists. Must ensure that each parameter mentioned in section Parameters is in the callable’s signature. Must ensure that each parameter in the callable’s signature is mentioned in section Parameters. Must ensure that each exception listed in section Raises refers to an existing class. Must ensure that each exception listed in section Raises is a subclass of BaseException. Must resolve each exception listed in section Raises by importing the longest module prefix and traversing remaining attributes; must fall back to the callable’s globals, its defining module, and builtins. Must collect warnings in the tracer object passed.
Parameters	tr Tracer for providing context and collecting warnings. obj The callable object to validate against. top The docitem tree to validate. node_contract The node for section Contract already parsed by the caller. node_normative_sections The node for section Preamble.normative_sections already parsed by the caller. session The validation session shared across recursive validations.
Returns	Must return None
Raises	ValidationError Must raise if any of the validation conditions listet in general fails.
Notes	Usage This function is typically not called directly. Please call validate_docstring instead.
Function	validate_docstring_method

11.1.5.2. validate_docstring_class

Signature	sdv.doc.waterloo.docitem_validator.validate_docstring_class( tr: tracer obj: object top: docitem_docstring_class node_contract: docitem_map_base node_normative_sections: docitem_list_base session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must validate the docitem tree top against the class object obj. Must ensure that sections general, constructor, api exist. Must ensure that each section listed in api is normative. Must ensure that subsection traits – if exists – contains only allowed values and no duplicates. Must ensure that section Derived_from exists if listed in normative_sections. Must ensure that each entry in Derived_from is a base class of obj.__class__. Must enforce normativity/existence consistency for Class_overview, Method_overview, Public_variables, Public_constants: Must collect errors and warnings in the tracer object passed.
Parameters	tr Tracer for providing context and collecting warnings. obj The callable object to validate against. top The docitem tree to validate. node_contract The node for section Contract already parsed by the caller. node_normative_sections The node for section Preamble.normative_sections already parsed by the caller. session The validation session shared across recursive validations.
Returns	Must return None
Raises	ValidationError Must raise if any of the validation conditions listet in general fails. Must raise if a section exists but is not listed as normative. Must raise if a section is listed as normative but does not exist.
Notes	Usage This function is typically not called directly. Please call validate_docstring instead. Last review 2026-01-23
Function	validate_docstring_class

11.1.5.3. validate_docstring_module

Signature	sdv.doc.waterloo.docitem_validator.validate_docstring_module( tr: tracer obj: object top: docitem_docstring_module node_contract: docitem_map_base node_normative_sections: docitem_list_base session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must validate the docitem tree top against the module object obj. Must ensure that Contract contains sections general and api. Must ensure that all sections declared as normative exist. Must enforce normativity/existence consistency for Class_overview, Function_overview, Public_types, Public_variables, Public_constants: Must collect errors and warnings in the tracer object passed.
Parameters	tr Tracer for providing context and collecting warnings. obj The callable object to validate against. top The docitem tree to validate. node_contract The node for section Contract already parsed by the caller. node_normative_sections The node for section Preamble.normative_sections already parsed by the caller. session The validation session shared across recursive validations.
Returns	Must return None
Raises	ValidationError Must raise if any of the validation conditions listet in general fails. Must raise if a section exists but is not listed as normative. Must raise if a section is listed as normative but does not exist.
Notes	Usage This function is typically not called directly. Please call validate_docstring instead. Last review 2026-01-23
Function	validate_docstring_module

11.1.5.4. validate_docstring

Signature	sdv.doc.waterloo.docitem_validator.validate_docstring( tr: tracer obj: object top: docitem_docstring_base | None session: DocSession ) -> docitem_docstring_base
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope public
Contract	general Must validate the docitem tree top against the object obj if top is not None. Must analyze the docstring of obj and create a docitem tree if top is None. Must ensure that section Preamble exists. Must ensure that subsection profile exists in section Preamble. Must ensure that subsection profile contains exactly one item. Must ensure that the item in subsection profile is an identifier. Must ensure that the item in subsection profile is one of the allowed profiles. Must ensure that the item in subsection profile matches the object type. Must ensure that subsection normative_sections exists in section Preamble. Must ensure that each item in subsection normative_sections refers to an existing section. Must ensure that no item in subsection normative_sections appears more than once. Must ensure that each section which contains at least one of the normativity keywords is listed under normative_sections, unless the section is explicitly declared informative by the active profile/template. Must ensure that section Contract exists. Must ensure that section Contract is listed in subsection normative_sections. Must ensure that section Definitions –provided it exists– is listed in subsection normative_sections, regardless of whether it contains normativity keywords. Must look for ocurrences of token |term|`<Identifier>` in the docitem tree and ensure that the referenced term is defined in section Definitions. Must ensure that section Terminology –provided it exists– is considered informative and NOT listed in subsection normative_sections. Must enforce profile related tests depending on the profile and call one of the validators validate_docstring_*. Must examine section See_also if it exists. Must ensure the existence of each item listed in See_also. Must ensure that each item listed in See_also has a valid docstring.
Parameters	tr Tracer for providing context and collecting warnings. obj The object to validate against (module, class or callable). top The docitem tree to validate. session The validation session shared across recursive validations.
Returns	Must return None
Raises	ValidationError Must raise if any of the validation conditions listet in general fails.
Notes	Usage This function should be pretty easy to use, if you leave out parameter top. You simply pass the object, the docstring of which you would like to validate. Note, however, that this function only validates for inner consistency of the the docstring, it does not validate for coverage (i.e. check existence and docstrings of all objects inside the class)
See also	validate_class_coverage, validate_module_coverage
Function	validate_docstring

11.1.6. Coverage validators

11.1.6.1. validate_class_class_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_class_class_coverage( tr: tracer obj: type[object] doc_class: docitem_docstring_class session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze nested classes documented in Public_classes. Must ensure that each entry in Public_classes resolves to a nested class with a valid docstring. Should ensure that each nested class with a valid docstring is listed in section Public_classes.
Parameters	tr Tracer for providing context and collecting warnings. obj The class object to be validated. doc_class Already parsed class docstring tree for obj. session The validation session shared across recursive validations.
Returns	Must return None.
Raises	TypeError Must raise if obj is not a class object. ValidationError Must raise if validation fails.
Notes	Last review 2026-02-04
Function	validate_class_class_coverage

11.1.6.2. validate_class_method_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_class_method_coverage( tr: tracer obj: type[object] doc_class: docitem_docstring_class session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze methods documented in Public_methods. Must ensure that each entry in Public_methods resolves to a method with a valid docstring. Should ensure that each method with a valid docstring is listed in section Public_methods.
Parameters	tr Tracer for providing context and collecting warnings. obj The class object to be validated. doc_class Already parsed class docstring tree for obj. session The validation session shared across recursive validations.
Returns	Must return None.
Raises	TypeError Must raise if obj is not a class object. Must raise if doc_class is not a docitem_docstring_class. ValidationError Must raise if validation fails.
Notes	Last review 2026-02-04
Function	validate_class_method_coverage

11.1.6.3. validate_class_constant_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_class_constant_coverage( tr: tracer obj: type[object] doc_class: docitem_docstring_class session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze the docstrings of the class object passed. Must ensure that each constant listed in Public_constants exists. Must ensure that each constant listed in Public_constants is annotated as Final or not annotated at all.
Parameters	tr Tracer for providing context and collecting warnings. obj The class object to be validated. doc_class Already parsed class docstring tree for obj. session Validation session for tracking state across validations.
Returns	Must return None.
Raises	TypeError Must raise if obj is not a class object. ValidationError Must raise if validation fails.
Function	validate_class_constant_coverage

11.1.6.4. validate_class_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_class_coverage( tr: tracer obj: type[object] ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must validate for class, method, type, constant, and variable coverage by calling the specific coverage validators.
Parameters	tr Tracer for providing context and collecting warnings. obj The class object to be validated.
Returns	Must return None.
Raises	ValidationError Must propagate exceptions from subordinate coverage validators.
Notes	todo Missing: class-type-coverage.
Function	validate_class_coverage

11.1.6.5. validate_module_class_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_module_class_coverage( tr: tracer obj: ModuleType doc_module: docitem_docstring_module session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze classes documented in Public_classes. Must ensure that each entry in Public_classes resolves to a class with a valid docstring. Should ensure that each class with a valid docstring is listed in section Public_classes.
Parameters	tr Tracer for providing context and collecting warnings. obj The module object to be validated. doc_module Already parsed module docstring tree for obj. session Validation session for tracking state across validations.
Returns	Must return None.
Raises	ValidationError Must raise if validation fails.
Notes	Last review 2026-02-04
Function	validate_module_class_coverage

11.1.6.6. validate_module_function_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_module_function_coverage( tr: tracer obj: ModuleType doc_module: docitem_docstring_module session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze functions documented in Public_functions. Must ensure that each entry in Public_functions resolves to a function with a valid docstring. Should ensure that each function with a valid docstring is listed in section Public_functions.
Parameters	tr Tracer for providing context and collecting warnings. obj The module object to be validated. doc_module Already parsed module docstring tree for obj. session Validation session for tracking state across validations.
Returns	Must return None.
Raises	TypeError Must raise if obj is not a module object. Must raise if doc_module is not a docitem_docstring_module. ValidationError Must raise if validation fails.
Notes	Last review 2026-02-04
Function	validate_module_function_coverage

11.1.6.7. validate_module_type_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_module_type_coverage( tr: tracer obj: ModuleType doc_module: docitem_docstring_module session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze the docstrings of the module object passed. Must ensure that each type listed in the module’s Public_types section exists in the module.
Parameters	tr Tracer for providing context and collecting warnings. obj The module object to be validated. doc_module Already parsed module docstring tree for obj. session Validation session for tracking state across validations.
Returns	Must return None.
Raises	ValidationError Must raise if validation fails.
Function	validate_module_type_coverage

11.1.6.8. validate_module_constant_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_module_constant_coverage( tr: tracer obj: ModuleType doc_module: docitem_docstring_module session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze the docstrings of the module object passed. Must ensure that each constant listed in the module’s Public_constants section exists in the module. Must ensure that each constant listed in the module’s Public_constants is either annotated as Final or not annotated at all.
Parameters	tr Tracer for providing context and collecting warnings. obj The module object to be validated. doc_module Already parsed module docstring tree for obj. session Validation session for tracking state across validations.
Returns	Must return None.
Raises	ValidationError Must raise if validation fails.
Function	validate_module_constant_coverage

11.1.6.9. validate_module_variable_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_module_variable_coverage( tr: tracer obj: ModuleType doc_module: docitem_docstring_module session: DocSession ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze the docstrings of the module object passed. Must ensure that each variable listed in the module’s Public_variables section exists in the module.
Parameters	tr Tracer for providing context and collecting warnings. obj The module object to be validated. doc_module Already parsed module docstring tree for obj. session Validation session for tracking state across validations.
Returns	Must return None.
Raises	ValidationError Must raise if validation fails.
Function	validate_module_variable_coverage

11.1.6.10. validate_module_coverage

Signature	sdv.doc.waterloo.docitem_validator.validate_module_coverage( tr: tracer obj: ModuleType ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must validate for class, function, type, constant, and variable coverage by calling the specific coverage validators.
Parameters	tr Tracer for providing context and collecting warnings. obj The module object to be validated.
Returns	Must return None.
Raises	ValidationError Must raise if validation fails.
Function	validate_module_coverage

11.1.7. Additional helpers

11.1.7.1. gen_documentable_objects

Signature	sdv.doc.waterloo.docitem_helper.gen_documentable_objects( obj: Documentable config: ConfigTraversal = ConfigTraversal() ) -> Generator[Documentable, None, None]
Preamble	normative sections Contract, Parameters, Returns, Raises scope public
Contract	general Must create a generator object which allows depth-first tree traversal of objects in obj. Must first yield object obj itself. Must yield all objects and only objects which can have a docstring.
Parameters	obj The object (module, class, function, method) to examine. config Controls acceptance or refusal of objects during traversal.
Returns	Must return a Generator which yields objects from tree traversal of obj
Raises	<empty>
Function	gen_documentable_objects

Example

import sdv.doc.waterloo.docitem as wtrl
import importlib
import sys

def main(mod_name: str) -> None:
# Configure traversal
	cfg = wtrl.ConfigTraversal()
# Allow recursive traversal
	cfg.enable_include_imported()

# Open module
	mod = importlib.import_module(mod_name)

# Iterate over documentable objects
	objs = wtrl.gen_documentable_objects(mod,cfg)
	for obj in objs:
		print(wtrl.get_obj_name(obj))

if __name__ == "__main__":
	main("pytest_good_inheritance")

11.1.7.2. get_tree_of_section

Signature	sdv.doc.waterloo.docitem_tokenizer.get_tree_of_section( tr: tracer tree: DocstringTree sec: str ) -> DocstringSubtree
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must iterate over the given docitem tree and read the label (label) and subtree pairs. Must interpret sec as section label (without trailing colon), try to match label against sec and return the subtree on success.
Parameters	tr Tracer for providing context and collecting warnings tree The docitem tree to be examined sec The section label to search for.
Returns	Must return the subtree of the found section.
Raises	SectionNotFoundError Must raise if the section is not found. BaseException May propagate exceptions from expect_label May propagate exceptions from expect_list
Function	get_tree_of_section

11.1.7.3. get_tree_of_subsection

Signature	sdv.doc.waterloo.docitem_tokenizer.get_tree_of_subsection( tr: tracer tree: DocstringTree sec: str subsec: str ) -> DocstringSubtree
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must iterate over the given docitem tree and read the label (label) and subtree pairs. Must interpret sec as section label (without trailing colon), try to match label against sec. On successful match: Must iterate over the subtree and read the label (sublabel) and subtree pairs. Must interpret subsec as subsection label (without trailing colon), try to match the sublabel against subsec and return the subtree on success.
Parameters	tr Tracer for providing context and collecting warnings tree The docitem tree to be examined sec The section label to search for. subsec The subsection label to search for.
Returns	Must return the subtree of the found subsection.
Raises	SectionNotFoundError Must raise if the section is not found. SubsectionNotFoundError Must raise if the subsection is not found. BaseException May propagate exceptions from expect_label May propagate exceptions from expect_list
Function	get_tree_of_subsection

11.1.7.4. get_scopes_of_tree

Signature	sdv.doc.waterloo.docitem_tokenizer.get_scopes_of_tree( tr: tracer tree: DocstringTree ) -> Scopes
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must extract the Preamble from the docstring tree. Must extract the scope from the Preamble. Must return the default if scope is not present or empty.
Parameters	tr Tracer for providing context and collecting warnings tree The docitem tree to be examined
Returns	Must return the set of scopes found, or the default., which is a set containing a single element PUBLIC.
Raises	SectionNotFoundError Must raise if there is no Preamble
Function	get_scopes_of_tree

11.1.7.5. to_string_tree

Signature	sdv.doc.waterloo.docitem_tokenizer.to_string_tree( tree: DocstringSubtree indent_scheme: int = 0 indent: int = 0 ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render the docstring tree to a string, using the indentation scheme passed. Must generate a waterloo docstring, provided the input is a docstring tree from a waterloo docstring.
Parameters	tree The docstring tre to render indent_scheme The indentation scheme to use, must be one of { INDENT_SCHEME_TAB, INDENT_SCHEME_SPC4 } indent Current indent level (recursive function). May be used for providing an overall indentation by the caller.
Returns	Must return the rendered string.
Raises	<empty>
Description	This function is helpful for idempotence tests. It is invoked e.g. in waterlint extract in order to extract sections or subsections from a docstring.
Function	to_string_tree

11.1.7.6. build_anchor

Signature	sdv.doc.waterloo.docitem_helper.build_anchor( obj: object kind: str | None = None ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must build a deterministic anchor string from an object. Must use the fully qualified name as source. Must encode each qualified-name segment as <len>:<segment>. Must prefix the anchor by wtrl-<kind>-. Must infer kind as one of mod, cls, func, obj if not passed explicitly.
Parameters	obj Object for which the anchor shall be generated. kind Optional explicit kind tag.
Returns	Deterministic anchor string suitable for doc-internal links.
Raises	<empty>
Notes	Last review 2026-06-22
Function	build_anchor

11.1.8. Diagnostics helpers

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

11.1.8.1. explain_try_self_for_section

Signature	sdv.doc.waterloo.docitem_diagnostics.explain_try_self_for_section( label: str profile: str ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must build the canonical self-explanation command for a section label and profile.
Parameters	label The section label to explain. profile The docstring profile to use as the explain context.
Returns	The canonical explain-section command for the given label and profile.
Raises	<empty>
See also	explain_try_self_for_subsection
Function	explain_try_self_for_section

11.1.8.2. explain_try_self_for_subsection

Signature	sdv.doc.waterloo.docitem_diagnostics.explain_try_self_for_subsection( label: str profile: str ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must build the canonical self-explanation command for a fully qualified subsection label and profile.
Parameters	label The fully qualified subsection label to explain. profile The docstring profile to use as the explain context.
Returns	The canonical explain-subsection command for the given label and profile.
Raises	<empty>
See also	explain_try_self_for_section
Function	explain_try_self_for_subsection

11.1.8.3. render_allowed_identifier

Signature	sdv.doc.waterloo.docitem_diagnostics.render_allowed_identifier( label: str identifiers: Iterable[str] ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render a compact snippet for a subsection that expects one identifier.
Parameters	label The subsection label to render. identifiers The allowed identifier values.
Returns	A compact list of lines that states the allowed identifier values in one line.
Raises	<empty>
Function	render_allowed_identifier

11.1.8.4. render_allowed_identifiers

Signature	sdv.doc.waterloo.docitem_diagnostics.render_allowed_identifiers( label: str identifiers: Iterable[str] ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render a compact snippet for a subsection that expects a list of identifiers.
Parameters	label The subsection label to render. identifiers The allowed identifier values.
Returns	A compact list of lines that states the allowed identifier values in one line.
Raises	<empty>
Function	render_allowed_identifiers

11.1.8.5. render_base_method_docstring_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_base_method_docstring_details( base_name: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a base-method docstring problem.
Parameters	base_name The base method name found in Contract.base. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_base_method_docstring_details

11.1.8.6. render_base_method_reference_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_base_method_reference_details( current_entries: Iterable[str] expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a Contract.base reference problem.
Parameters	current_entries The current raw entries found in Contract.base. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_base_method_reference_details

11.1.8.7. render_constant_reference_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_constant_reference_details( label: str const_name: str expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a Public_constants reference problem.
Parameters	label The subsection label to render. const_name The constant entry name found in the subsection. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_constant_reference_details

11.1.8.8. render_deduplicated_identifiers

Signature	sdv.doc.waterloo.docitem_diagnostics.render_deduplicated_identifiers( label: str identifiers: Iterable[str] ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render a compact snippet for a subsection after removing duplicate identifiers.
Parameters	label The subsection label to render. identifiers The identifier values with duplicates removed while preserving the first occurrence order.
Returns	A compact list of lines that states the deduplicated identifier values in one line.
Raises	<empty>
Function	render_deduplicated_identifiers

11.1.8.9. render_definition_reference_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_definition_reference_details( references: str | Iterable[str] profile: str missing_definitions: bool ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a term reference problem in Definitions.
Parameters	references The term reference or term references found in the docstring body. profile The docstring profile used for the explain-section or explain-subsection hint. missing_definitions Whether the Definitions section itself is missing.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_definition_reference_details

11.1.8.10. render_exactly_one_identifier_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_exactly_one_identifier_details( label: str current_entries: Iterable[str] profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a subsection that must contain exactly one identifier.
Parameters	label The qualified subsection label to render in the snippets and hint. current_entries The current raw entries from the subsection. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_exactly_one_identifier_details

11.1.8.11. render_expected_identifier

Signature	sdv.doc.waterloo.docitem_diagnostics.render_expected_identifier( label: str expected_kind: Literal[‘identifier’, ‘qualified identifier’] ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render the expected syntax for a single identifier-like value.
Parameters	label The subsection label to render. expected_kind Use identifier or qualified identifier to describe the expected syntax class.
Returns	A compact list of lines that states the expected syntax in the Waterloo snippet format.
Raises	<empty>
Function	render_expected_identifier

11.1.8.12. render_expected_snippet

Signature	sdv.doc.waterloo.docitem_diagnostics.render_expected_snippet( section_label: str | None subsections: Iterable[str] | None = None ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render the canonical expected snippet for a section.
Parameters	section_label The section label to render. subsections The subsection labels to render under the section label.
Returns	The canonical expected section snippet as a list of lines.
Raises	<empty>
Function	render_expected_snippet

11.1.8.13. render_identifier_lines

Signature	sdv.doc.waterloo.docitem_diagnostics.render_identifier_lines( label: str identifiers: Iterable[str] ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render the found identifiers of a list-valued subsection in a compact form.
Parameters	label The subsection label to render. identifiers The identifier values exactly as found.
Returns	A compact list of lines that states the identifier values in one line without semantic normalization.
Raises	<empty>
Function	render_identifier_lines

11.1.8.14. render_inherited_definition_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_inherited_definition_details( current_inherited_terms: Iterable[str] profile: str expected_text: str use_section_hint: bool = False ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for an inherited Definitions problem.
Parameters	current_inherited_terms The inherited definition terms found in the current object. profile The docstring profile used for the explain-subsection hint. expected_text The minimal correction or instruction to show in the expected snippet. use_section_hint Whether the hint should point to the section-level explain-section entry instead of the subsection-level inherited definition entry.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_inherited_definition_details

11.1.8.15. render_listed_object_missing_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_listed_object_missing_details( label: str member_name: str expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render compact validation details for a listed object that has no matching runtime object.
Parameters	label The section label to render. member_name The listed entry name that has no matching object. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the explain-section hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_listed_object_missing_details

11.1.8.16. render_missing_entry_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_missing_entry_details( container_label: str current_entries: Iterable[str] missing_entry: str profile: str top_level: bool = False ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a missing entry in a section-like container.
Parameters	container_label The section label that contains the missing entry. current_entries The currently present entry labels in the container. missing_entry The entry label that should be added. profile The docstring profile used for the explain-* hint. top_level Use a top-level list rendering when the container itself is the document root rather than a nested section.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_missing_entry_details

11.1.8.17. render_name_object_consistency_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_name_object_consistency_details( label: str current_entries: Iterable[str] profile: str overview_item: str | None = None ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render compact validation details for name/object consistency checks.
Parameters	label The section label to render. current_entries The current raw entries from the section. profile The docstring profile used for the hint. overview_item If provided, render an overview entry instead of a flat identifier list.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_name_object_consistency_details

11.1.8.18. render_named_value_reference_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_named_value_reference_details( label: str name: str expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a Public_variables reference problem.
Parameters	label The subsection label to render. name The variable entry name found in the subsection. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_named_value_reference_details

11.1.8.19. render_normative_section_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_normative_section_details( section_label: str normative_sections: Iterable[str] profile: str action: Literal[‘add’, ‘remove’] ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for normative section membership checks.
Parameters	section_label The section label that should be added to or removed from the normative section set. normative_sections The current normative section labels. profile The docstring profile used for the explain-section hint. action Either add when the section should be present, or remove when it should be absent.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_normative_section_details

11.1.8.20. render_normativity_keyword_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_normativity_keyword_details( section_label: str entry_name: str current_lines: Iterable[str] suggestion: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for an entry that must not contain normativity keywords.
Parameters	section_label The overview section label, such as Class_overview. entry_name The entry label that violates the rule. current_lines The raw lines found in the entry. suggestion A brief informative replacement suggestion for the entry. profile The docstring profile used for the explain-section hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_normativity_keyword_details

11.1.8.21. render_overview_missing_member_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_overview_missing_member_details( overview_label: str public_label: str current_entries: Iterable[str] missing_name: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for an overview entry that is missing from its matching Public_* section.
Parameters	overview_label The overview section label, such as Class_overview. public_label The matching public section label, such as Public_classes. current_entries The current raw entries from the overview section. missing_name The entry name that is missing from the public section. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_overview_missing_member_details

11.1.8.22. render_overview_requires_section_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_overview_requires_section_details( overview_label: str required_section: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render compact validation details for overview sections that require a normative companion section.
Parameters	overview_label The overview section label, such as Class_overview. required_section The normative section that must be added, such as Public_classes. profile The docstring profile used for the explain-section hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_overview_requires_section_details

11.1.8.23. render_parameter_signature_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_parameter_signature_details( section_label: str current_entries: Iterable[str] expected_entries: Iterable[str] profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a parameter/signature mismatch.
Parameters	section_label The label to render in the snippets. current_entries The current raw parameter entries. expected_entries The corrected parameter entries to show in the expected snippet. profile The docstring profile used for the explain-section hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_parameter_signature_details

11.1.8.24. render_profile_mismatch_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_profile_mismatch_details( object_name: str object_kind: str current_profile: str expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render compact validation details for a profile mismatch.
Parameters	object_name The documented object name. object_kind The detected object kind such as module, class, function or method-like. current_profile The profile found in the docstring. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_profile_mismatch_details

11.1.8.25. render_scope_relation_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_scope_relation_details( containing_kind: str containing_scopes: Scopes is_containing_scope_explicit: bool contained_kind: str contained_scopes: Scopes is_contained_scope_explicit: bool section_label: str reference: str expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a scope monotonicity violation.
Parameters	containing_kind The kind of the containing object, such as module or class. containing_scopes The scopes of the containing object. is_containing_scope_explicit Whether the containing object declared its scope explicitly. contained_kind The kind of the contained object, such as function, class, or method. contained_scopes The scopes of the contained object. is_contained_scope_explicit Whether the contained object declared its scope explicitly. section_label The section label to render. reference The offending reference as found in the source section. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_scope_relation_details

11.1.8.26. render_see_also_reference_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_see_also_reference_details( reference: str expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a See_also reference mismatch.
Parameters	reference The raw reference text as found in the See_also section. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the explain-section hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_see_also_reference_details

11.1.8.27. render_source_snippet

Signature	sdv.doc.waterloo.docitem_diagnostics.render_source_snippet( section_label: str | None subsections: Iterable[str] | None = None ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render a compact section snippet with canonical subsection ordering.
Parameters	section_label The section label to render. subsections The subsection labels to render under the section label. If omitted, the canonical order for the section is used when available.
Returns	A compact list of lines that renders the section label followed by subsection placeholders.
Raises	<empty>
Function	render_source_snippet

11.1.8.28. render_suggestion

Signature	sdv.doc.waterloo.docitem_diagnostics.render_suggestion( label: str | None suggestion: str ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render a suggestion snippet for a section or subsection in order to fix the docstring. Must add angle brackets around the suggestion to indicate that it is a placeholder for the actual content. requires The suggestion should be a brief and concise plain single line text.
Parameters	label The section or subsection label (as qualified name) to render. An empty label means the suggestion is not bound to a specific section or subsection. suggestion A brief suggestion of what the section or subsection could be or contain.
Returns	A compact list of lines that states the suggested section or subsection in one line.
Raises	<empty>
Function	render_suggestion

11.1.8.29. render_type_reference_details

Signature	sdv.doc.waterloo.docitem_diagnostics.render_type_reference_details( label: str type_name: str expected_text: str profile: str ) -> dict[str, Any]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must build standardized validation details for a Public_types reference problem.
Parameters	label The subsection label to render. type_name The type entry name found in the subsection. expected_text The minimal correction or instruction to show in the expected snippet. profile The docstring profile used for the explain-subsection hint.
Returns	A details dictionary with found, expected, and hint.
Raises	<empty>
Function	render_type_reference_details

11.1.8.30. render_unique_identifiers

Signature	sdv.doc.waterloo.docitem_diagnostics.render_unique_identifiers( label: str identifiers: Iterable[str] ) -> list[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render a compact snippet for a subsection that requires unique identifiers.
Parameters	label The subsection label to render. identifiers The canonical identifier values.
Returns	A compact list of lines that states the canonical identifier values and mentions uniqueness.
Raises	<empty>
Function	render_unique_identifiers

Default module qualifier sdv.doc.waterloo.docitem_diagnostics ends here. New default: sdv.doc.waterloo.docitem.

Default module qualifier sdv.doc.waterloo.docitem ends here. New default: sdv.doc.waterloo.

11.1.9. Enum classes

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

11.1.9.1. sdv.doc.waterloo.docitem_helper.Scope

Preamble	normative sections Contract, Public constants, Derived from scope public
Contract	general Must provide constants representing available scopes. Must provide a time-stable partial order for the constants. constructor Inherit from int.
Derived from	IntEnum
Public constants	PUBLIC Selects the public API. EXTENSION Selects the API for developers of plugin and extensions. CORE Selects the API for core developers.
Notes	Purpose The scope is an optional parameter for rendering functions. It allows to restrict the set of rendered objects to a well-defined audience. Values The class only ensures the partial order but does not ensure particular values for the constants.
Class	Scope

11.1.9.2. sdv.doc.waterloo.docitem_helper.Flavour

Preamble	normative sections Contract, Public constants, Derived from scope public
Contract	general Must provide constants representing available flavours for rendering Normativity Keywords. constructor Inherit from int.
Derived from	IntEnum
Public constants	RAW Example: | + Must + | RFC_2119 Example: MUST MARKDOWN Example: **MUST**
Class	Flavour

11.1.9.3. sdv.doc.waterloo.docitem_helper.Format

Preamble	normative sections Contract, Public constants, Derived from scope public
Contract	general Must provide constants representing available output formats for string rendering. constructor Inherit from int.
Derived from	IntEnum
Public constants	JSON Javascript Object Notation MD Markdown.
Class	Format

11.1.9.4. sdv.doc.waterloo.docitem_helper.Status

Preamble	normative sections Contract, Public constants, Derived from scope public
Contract	general Must provide constants representing the values of subsection Preamble.status. constructor Inherit from StrEnum.
Derived from	StrEnum
Public constants	EXPERIMENTAL See rule STA-004. STABLE See rule STA-004. FROZEN See rule STA-004. DEPRECATED See rule STA-004. DRAFT See rule STA-004.
Notes	LoII This docstring violates LoII in order to preserve SSoT, see Public_constants.
Class	Status

Default module qualifier sdv.doc.waterloo.docitem_helper ends here. New default: sdv.doc.waterloo.

11.1.10. Helper classes

11.1.10.1. tracer

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

Nested classes in tracer

Preamble	normative sections Contract, Derived from
Contract	general Must define the following severity levels for filtering the tracer’s output: DEBUG: for debugging notes, not relevant for end-users. INFO: for informational messages that are relevant for end-users but do not indicate any problems. WARNING: for potential issues that should be looked at but do not necessarily indicate a failure. ERROR: for definite problems that indicate a failure to meet a requirement or rule. Must assign integer values to these levels in increasing order of severity, starting with 0 for DEBUG. constructor Must inherit from IntEnum.
Derived from	IntEnum
Class	tracer.Severity

Public Methods in class 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 wtrl-tracer-json-X.Y.Z.schema.json where X.Y.Z is the declared schema version.
Raises	<empty>
Method	tracer.build_json

Signature	sdv.doc.waterloo.docitem_helper.tracer.str_by_severity( severity: Severity ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must render the tracer’s content as a human-readable string, filtered by severity level. Must include entries with severity level equal to or higher than the specified level. Must format entries with clear labels and context for easy understanding.
Parameters	severity Only include entries with this severity level or higher. Levels are ordered as DEBUG < INFO < WARNING < ERROR.
Returns	A string representation of the tracer’s content, including entries up to the specified severity level, formatted for human readability.
Raises	<empty>
Notes	Called by This method is invoked by the __str__ method, which defaults to showing all entries (DEBUG level), so generally you simply call :wtrl_func:`str`(tracer_instance) to get the full content or :wtrl_func:`print`(tracer_instance) to display it.
Method	tracer.str_by_severity

11.1.10.2. ConfigTraversal

Preamble	normative sections Contract scope public
Contract	general Must provide public methods to configure object traversal for functions like gen_documentable_objects. Must provide (internal) boolean methods which accept or refuse traversal at a given node in the object tree. constructor Must be default-constructible
Notes	Experimental This class will likely be expanded in the future, and we are postponing the normative documentation for now. Configure Use enable_include_imported to allow descending into imported modules. Future Possible extensions include acceptance/refusal by regular expressions. Example gen_documentable_objects
Class	ConfigTraversal

11.1.11. Base classes

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

11.1.11.1. docitem_base

Preamble	normative sections Contract, Derived from, Public methods
Terminology	child item A string or an instance of a docitem class.
Contract	general Must provide an abstract method for parsing a docstring tree. Must provide an abstract method for accessing child items. constructor Must be default-constructible. traits abstract
Derived from
Public methods	parse, items
Method overview	parse Parse a docstring subtree and create child nodes accordingly. items Return an iterable over the child items.
Class	docitem_base

Public Methods in class docitem_base

Signature	sdv.doc.waterloo.docitem_base.docitem_base.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Description	This docstring is located in the base class of all docitem node classes. The method is not implemented here and will raise an exception if it is invoked without a corresponding implementation in a derived class.
Contract	general Must parse a docstring subtree and create the related child items. requires subtree must be a formally correct docstring subtree from a Waterloo docstring; otherwise parsing will fail.
Parameters	tr The tracer for collecting diagnostics. subtree A subtree of the tree matching this instance.
Returns	None
Raises	NotImplementedError Must raise if not implemented in the derived class. RuntimeError Must raise if the subtree does not match the expected format.
Method	docitem_base.parse

Signature	sdv.doc.waterloo.docitem_base.docitem_base.items( ) -> Iterable[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general ensures Must not mutate the instance (pure getter)
Parameters
Returns	Must return an iterable over the child items.
Raises	NotImplementedError Must raise if not implemented in the derived class.
Method	docitem_base.items

11.1.11.2. docitem_list_base

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must contain a container of str and expose it as an iterable object. constructor Must be default-constructible. traits abstract
Derived from	docitem_base
Public methods	items
Method overview	items Access to the string list
Class	docitem_list_base

Public Methods in class docitem_list_base

Signature	sdv.doc.waterloo.docitem_base.docitem_list_base.items( ) -> List[str]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must not mutate the instance (pure getter)
Parameters
Returns	Must return the forementioned container of strings.
Raises	<empty>
Description
Method	docitem_list_base.items

11.1.11.3. docitem_map_base

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must contain a map-like container from str to docitem_base and expose it as an iterable object. constructor Must be default-constructible. traits abstract
Derived from	docitem_base
Public methods	items
Method overview	items Access to the item-node map
Class	docitem_map_base

Public Methods in class docitem_map_base

Signature	sdv.doc.waterloo.docitem_base.docitem_map_base.items( ) -> Dict[str, docitem_base]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must not mutate the instance (pure getter)
Parameters
Returns	Must return an iterable over the child items.
Raises	<empty>
Method	docitem_map_base.items

11.1.11.4. docitem_docstring_base

Preamble	normative sections Contract, Derived from, Public methods scope public
Contract	general Must represent a docstring. Must accept sections as defined in the derived classes. constructor Must be default-constructible traits abstract
Derived from	docitem_map_base
Public methods	parse, scopes, is_visible, can_see, is_scope_compatible
Method overview	parse Parse a docstring tree.
Class	docitem_docstring_base

Public Methods in class docitem_docstring_base

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_base.parse( tr: tracer tree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must accept a complete docstring tree according to the map returned by the derived class’ method dispatch_map.
Parameters	tr The tracer for collecting diagnostics. tree The docstring tree
Returns	Must return None.
Raises	RuntimeError Must raise if Preamble is not the first section found. Must raise if an invalid section label is found. Must raise if parsing any of the sections fails. NotImplementedError Must raise if not invoked for an instance of a derived class.
Method	docitem_docstring_base.parse

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_base.scopes( ) -> Scopes
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must return the scopes assigned to the object in subsection Preamble.scope. Must fall back to the default value, if there is no subsection scope in Preamble. Must use {core} as default value, i.e. a set with a single element. requires Self must represent a formally correct Abstract Syntax Tree.
Parameters
Returns	A set of enum values representing the scopes of the documented object.
Raises	SectionNotFoundError Must raise if the tree has no Preamble.
Method	docitem_docstring_base.scopes

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_base.is_visible( sc_query: Scopes ) -> bool
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must test visibility of the documented object against a set of scopes passed. Visibility is given if the object has a scope with a value less than at least one scope in the set passed. requires Requirements of method scopes apply.
Parameters	sc_query The set of scopes to test visibility against.
Returns	Must return True iff there exists s_obj in the object’s scope set and s_query in sc_query such that s_obj <= s_query.
Raises	SectionNotFoundError May propagate from scopes.
Method	docitem_docstring_base.is_visible

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_base.can_see( sc_query: Scopes ) -> bool
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must test whether at least one scope in sc_query is at least as public as at least one scope in Self. This is the visibility relation used for upward references: a referenced object must be at least as public as the referencing object. requires Requirements of method scopes apply.
Parameters	sc_query The set of scope values of the referenced object.
Returns	True iff there exists s_query in sc_query and s_self in self.scopes() such that s_query <= s_self.
Raises	SectionNotFoundError May propagate from scopes.
Method	docitem_docstring_base.can_see

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_base.is_scope_compatible( obj_trg: docitem_docstring_base ) -> bool
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must test whether at least one scope in the referenced object obj_trg is at least as public as at least one scope in Self. This is the scope-compatibility relation used for reference edges: the referenced object must be at least as public as Self. requires Requirements of method scopes apply, for both Self and obj_trg.
Parameters	obj_trg The embedded, referenced or otherwise dependent object.
Returns	True if scopes are compatible, else False.
Raises	SectionNotFoundError May propagate from scopes.
Method	docitem_docstring_base.is_scope_compatible

11.1.11.5. docitem_free_text_entry_base

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent free-form text content for various sections. constructor Must be default-constructible. traits abstract
Derived from	docitem_list_base
Public methods	parse
Method overview	parse Parse free-form text lines.
Class	docitem_free_text_entry_base

Public Methods in class docitem_free_text_entry_base

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.11.6. docitem_list_of_symbols_base

Preamble	normative sections Contract, Definitions, Public classes, Public methods
Definitions	<Terms inherited from module> Identifier
Contract	general Must represent a list of symbols, each matching the pattern of an Identifier. constructor Must Be default-constructible traits abstract
Public classes	ValuePattern
Class overview	ValuePattern Enum type for selecting the regex to match against.
Public methods	_parse
Method overview	_parse Parse a list of symbols.
Class	docitem_list_of_symbols_base

Nested classes in docitem_list_of_symbols_base

Preamble	normative sections Contract, Definitions, Public constants
Definitions	<Terms inherited from module> Identifier, Qualified_Identifier
Contract	general Must be an Enum class. Must provide constants representing regular expressions for Identifier and Qualified_Identifier. constructor Must inherit the constructor from int, since the class is derived from IntEnum.
Public constants	IDENTIFIER Must represent the pattern of an Identifier. QUALIFIED_IDENTIFIER Must represent the pattern of a Qualified_Identifier.
Class	docitem_list_of_symbols_base.ValuePattern

Public Methods in class docitem_list_of_symbols_base

Signature	sdv.doc.waterloo.docitem_base.docitem_list_of_symbols_base._parse( tr: tracer refs: DocstringSubtree pattern: ValuePattern ) -> None
Preamble	normative sections Contract, Definitions, Parameters, Returns, Raises
Definitions	<Terms inherited from module> Identifier, Qualified_Identifier
Contract	general Must verify that the subtree passed (refs) is a list of strings. Must parse the content the list of strings and store them as items. Must ensure each string is an Identifier or Qualified_Identifier, as specified by parameter pattern.
Parameters	tr The tracer for collecting diagnostics. refs The docstring subtree to parse. pattern Specifies the pattern to match strings against, RE_IDENTIFIER or RE_QUALIFIED_IDENTIFIER.
Returns	Must return None.
Raises	ParseError Must raise if the items are not strings (no subtrees allowed). Must raise if the items (after splitting the CSV) are not (Qualified) Identifiers.
See also	sdv.doc.waterloo.docitem_helper.RE_IDENTIFIER, sdv.doc.waterloo.docitem_helper.RE_QUALIFIED_IDENTIFIER
Method	docitem_list_of_symbols_base._parse

11.1.12. Preamble node classes

11.1.12.1. docitem_profile

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the profile section, subsection of Preamble. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Parse a profile section.
Class	docitem_profile

Public Methods in class docitem_profile

Signature	sdv.doc.waterloo.docitem_preamble.docitem_profile.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of a profile section.
Parameters	tr The tracer for collecting diagnostics. refs The docstring subtree to parse.
Returns	Must return None.
Raises	RuntimeError Must raise if the number of items is not 1. Must raise if the item is not a string (no subtrees allowed). Must raise if the item is not an identifier.
Method	docitem_profile.parse

11.1.12.2. docitem_normative_sections

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the normative_sections section, subsection of Preamble. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Inherited method
Class	docitem_normative_sections

Public Methods in class docitem_normative_sections

Signature	sdv.doc.waterloo.docitem_preamble.docitem_normative_sections.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must set rules-on-fail in the tracer and delegate to the base implementation. base sdv.doc.waterloo.docitem.docitem_base.parse
Inherited_method	docitem_normative_sections.parse

11.1.12.3. docitem_status

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the status section, subsection of Preamble. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Parse a status section.
Class	docitem_status

Public Methods in class docitem_status

Signature	sdv.doc.waterloo.docitem_preamble.docitem_status.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of a status section.
Parameters	tr The tracer for collecting diagnostics. refs The docstring subtree to parse.
Returns	Must return None.
Raises	RuntimeError Must raise if the number of items is not 1. Must raise if the item is not a string (no subtrees allowed). Must raise if the item is not an identifier.
Method	docitem_status.parse

11.1.12.4. docitem_scope

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the scope section, subsection of Contract. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Inherited method
Class	docitem_scope

Public Methods in class docitem_scope

Signature	sdv.doc.waterloo.docitem_preamble.docitem_scope.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must set rules-on-fail in the tracer and delegate to the base implementation. base sdv.doc.waterloo.docitem.docitem_base.parse
Inherited_method	docitem_scope.parse

11.1.12.5. docitem_preamble

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Preamble section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse a Preamble section.
Class	docitem_preamble

Public Methods in class docitem_preamble

Signature	sdv.doc.waterloo.docitem_preamble.docitem_preamble.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the subsections of a Preamble section.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse.
Returns	Must return None.
Raises	RuntimeError Must raise if a subsection is not one of the allowed ones: {profile,normative_sections}.
Method	docitem_preamble.parse

11.1.13. Contract node classes

11.1.13.1. docitem_constructor

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the constructor section, subsection of Contract. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_base
Public methods	parse
Method overview	parse Parse a constructor section.
Class	docitem_constructor

Public Methods in class docitem_constructor

Signature	sdv.doc.waterloo.docitem_contract.docitem_constructor.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of a constructor section.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a list of strings.
Returns	Must return None.
Raises	RuntimeError Must raise if the items are not strings (no subtrees allowed). Must raise if the items are not identifiers.
Method	docitem_constructor.parse

11.1.13.2. docitem_general

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the general section, subsection of Contract. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_base
Public methods	parse
Method overview	parse Parse a general section.
Class	docitem_general

Public Methods in class docitem_general

Signature	sdv.doc.waterloo.docitem_contract.docitem_general.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of a general section.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a list of strings.
Returns	Must return None.
Raises	RuntimeError Must raise if the items are not strings (no subtrees allowed).
Method	docitem_general.parse

11.1.13.3. docitem_invariants

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the invariants section, subsection of Contract. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_base
Public methods	parse
Method overview	parse Parse a invariants section.
Class	docitem_invariants

Public Methods in class docitem_invariants

Signature	sdv.doc.waterloo.docitem_contract.docitem_invariants.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an invariants section.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a list of strings.
Returns	Must return None.
Raises	RuntimeError Must raise if the items are not strings (no subtrees allowed).
Method	docitem_invariants.parse

11.1.13.4. docitem_requires

Preamble	normative sections Contract, Derived from, Public methods
Description	This node represents the requires subsection of Contract. The subsection is intended to describe conditions the caller must satisfy before calling the documented function or method. The contents are treated as free-form text and are preserved verbatim for rendering and reporting.
Contract	general Must represent the requires section, subsection of Contract. Must be able to hold a list of free-form text lines. constructor Must be default-constructible.
Derived from	docitem_list_base
Public methods	parse
Method overview	parse Parse a requires section.
Class	docitem_requires

Public Methods in class docitem_requires

Signature	sdv.doc.waterloo.docitem_contract.docitem_requires.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of a requires section.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a list of strings.
Returns	Must return None.
Raises	RuntimeError Must raise if the items are not strings (no subtrees allowed).
Method	docitem_requires.parse

11.1.13.5. docitem_ensures

Preamble	normative sections Contract, Derived from, Public methods
Description	This node represents the ensures subsection of Contract. The subsection is intended to describe guarantees that hold after a successful call of the documented function or method. The contents are treated as free-form text and are preserved verbatim for rendering and reporting.
Contract	general Must represent the ensures section, subsection of Contract. Must be able to hold a list of free-form text lines. constructor Must be default-constructible.
Derived from	docitem_list_base
Public methods	parse
Method overview	parse Parse an ensures section.
Class	docitem_ensures

Public Methods in class docitem_ensures

Signature	sdv.doc.waterloo.docitem_contract.docitem_ensures.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an ensures section.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a list of strings.
Returns	Must return None.
Raises	RuntimeError Must raise if the items are not strings (no subtrees allowed).
Method	docitem_ensures.parse

11.1.13.6. docitem_traits

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the traits section, subsection of Contract. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Inherited method
Class	docitem_traits

Public Methods in class docitem_traits

Signature	sdv.doc.waterloo.docitem_contract.docitem_traits.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must set rules-on-fail in the tracer and delegate to the base implementation. base sdv.doc.waterloo.docitem.docitem_base.parse
Inherited_method	docitem_traits.parse

11.1.13.7. docitem_contract_module

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Contract section for profile module. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse a Contract section for profile module.
Class	docitem_contract_module

Public Methods in class docitem_contract_module

Signature	sdv.doc.waterloo.docitem_contract.docitem_contract_module.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an Contract section for profile module.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a set of concatenated sections.
Returns	Must return None.
Raises	RuntimeError Must raise if a section to be parsed is not one of the allowed ones: {general,:wtrl_label:api}.
Method	docitem_contract_module.parse

11.1.13.8. docitem_contract_class

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the contract section for profile class. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse a contract section for profile class.
Class	docitem_contract_class

Public Methods in class docitem_contract_class

Signature	sdv.doc.waterloo.docitem_contract.docitem_contract_class.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an Contract section for profile class.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a set of concatenated sections.
Returns	Must return None.
Raises	RuntimeError Must raise if a section to be parsed is not one of the allowed ones: {general,:wtrl_label:constructor,:wtrl_label:api}.
Method	docitem_contract_class.parse

11.1.13.9. docitem_contract_method

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the contract section for profile method or function. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse a contract section for profile method or function.
Class	docitem_contract_method

Public Methods in class docitem_contract_method

Signature	sdv.doc.waterloo.docitem_contract.docitem_contract_method.parse( tr: tracer subtree: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an Contract section for profile method or function.
Parameters	tr The tracer for collecting diagnostics. subtree The docstring subtree to parse, a set of concatenated sections.
Returns	Must return None.
Raises	RuntimeError Must raise if a section to be parsed is not one of the allowed ones: {general}.
Method	docitem_contract_method.parse

11.1.13.10. docitem_class_overview_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the content of an entry in section Class_overview. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of text lines describing the public class.
Class	docitem_class_overview_entry

Public Methods in class docitem_class_overview_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.14. Related objects node classes

11.1.14.1. docitem_class_overview

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Class_overview section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse the content of a section Class_overview.
Class	docitem_class_overview

Public Methods in class docitem_class_overview

Signature	sdv.doc.waterloo.docitem_sections.docitem_class_overview.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of section Class_overview.
Parameters	tr The tracer for collecting diagnostics. entries The docstring subtree to parse, a list of public class entries.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a set of public class entries. In detail: Must raise if the content is not a sequence of pairs label / list of strings.
Method	docitem_class_overview.parse

11.1.14.2. docitem_public_classes

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Public_classes section. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Inherited method
Class	docitem_public_classes

Public Methods in class docitem_public_classes

Signature	sdv.doc.waterloo.docitem_sections.docitem_public_classes.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must delegate to _parse in the base implementation. Must parse refs as a list of Qualified Identifiers. base sdv.doc.waterloo.docitem.docitem_list_of_symbols_base.parse
Notes	Last review 2026-02-23
Inherited_method	docitem_public_classes.parse

11.1.14.3. docitem_public_functions

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Public_functions section. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Inherited method
Class	docitem_public_functions

Public Methods in class docitem_public_functions

Signature	sdv.doc.waterloo.docitem_sections.docitem_public_functions.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must delegate to _parse in the base implementation. Must parse refs as a list of Qualified Identifiers. base sdv.doc.waterloo.docitem.docitem_list_of_symbols_base.parse
Notes	Last review 2026-02-23
Inherited_method	docitem_public_functions.parse

11.1.14.4. docitem_public_methods

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Public_methods section. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Inherited method
Class	docitem_public_methods

Public Methods in class docitem_public_methods

Signature	sdv.doc.waterloo.docitem_sections.docitem_public_methods.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must delegate to _parse in the base implementation. Must parse refs as a list of Qualified Identifiers. base sdv.doc.waterloo.docitem.docitem_list_of_symbols_base.parse
Notes	Last review 2026-02-23
Inherited_method	docitem_public_methods.parse

11.1.14.5. docitem_public_types_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the content of an entry in section Public_types. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of text lines describing the public type.
Class	docitem_public_types_entry

Public Methods in class docitem_public_types_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.14.6. docitem_public_types

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Public_types section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse the content of a section Public_types.
Class	docitem_public_types

Public Methods in class docitem_public_types

Signature	sdv.doc.waterloo.docitem_sections.docitem_public_types.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of section Public_types.
Parameters	tr The tracer for collecting diagnostics. entries The docstring subtree to parse, a list of public type entries.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a set of public type entries. In detail: Must raise if the content is not a sequence of pairs label / list of strings.
Method	docitem_public_types.parse

11.1.14.7. docitem_public_assignables_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the content of an entry in section Public_assignables. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of text lines describing the public assignable.
Class	docitem_public_assignables_entry

Public Methods in class docitem_public_assignables_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.14.8. docitem_public_assignables_base

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Public_assignables section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse the content of a section Public_assignables.
Class	docitem_public_assignables_base

Public Methods in class docitem_public_assignables_base

Signature	sdv.doc.waterloo.docitem_sections.docitem_public_assignables_base.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of section Public_assignables.
Parameters	tr The tracer for collecting diagnostics. entries The docstring subtree to parse, a list of public assignable entries.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a set of public assignable entries. In detail: Must raise if the content is not a sequence of pairs label / list of strings.
Method	docitem_public_assignables_base.parse

11.1.14.9. docitem_method_overview_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the content of an entry in section Method_overview. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of text lines describing the public method.
Class	docitem_method_overview_entry

Public Methods in class docitem_method_overview_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.14.10. docitem_method_overview

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Function_overview section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse the content of a section Function_overview.
Class	docitem_function_overview

Public Methods in class docitem_function_overview

Signature	sdv.doc.waterloo.docitem_sections.docitem_function_overview.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of section Function_overview.
Parameters	tr The tracer for collecting diagnostics. entries The docstring subtree to parse, a list of public function entries.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a set of public function entries. In detail: Must raise if the content is not a sequence of pairs label / list of strings.
Method	docitem_function_overview.parse

11.1.14.11. docitem_function_overview_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the content of an entry in section Function_overview. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of text lines describing the public function.
Class	docitem_function_overview_entry

Public Methods in class docitem_function_overview_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.14.12. docitem_function_overview

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Function_overview section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse the content of a section Function_overview.
Class	docitem_function_overview

Public Methods in class docitem_function_overview

Signature	sdv.doc.waterloo.docitem_sections.docitem_function_overview.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of section Function_overview.
Parameters	tr The tracer for collecting diagnostics. entries The docstring subtree to parse, a list of public function entries.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a set of public function entries. In detail: Must raise if the content is not a sequence of pairs label / list of strings.
Method	docitem_function_overview.parse

11.1.15. Other sections node classes

11.1.15.1. docitem_returns

Preamble	normative sections Contract, Public methods
Contract	general Must store the list of return value descriptions for a callable’s docstring. constructor Must be default-constructible.
Public methods	parse
Method overview	parse Parse a list of return descriptions.
Class	docitem_returns

Public Methods in class docitem_returns

Signature	sdv.doc.waterloo.docitem_sections.docitem_returns.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must accept a list of return descriptions. Must raise if the input is not a list of strings.
Parameters	tr The tracer for collecting diagnostics. lines A free-form text describing the return value.
Returns	Must return None.
Raises	RuntimeError Must raise if validation fails.
Method	docitem_returns.parse

11.1.15.2. docitem_parameters_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent an parameter entry in the Parameters section. Must accept and store a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse the content of a parameter entry.
Class	docitem_parameters_entry

Public Methods in class docitem_parameters_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.15.3. docitem_parameters

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Parameters section. Must accept and store a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse a list of parameters
Class	docitem_parameters

Public Methods in class docitem_parameters

Signature	sdv.doc.waterloo.docitem_sections.docitem_parameters.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Terminology	Parameter entry Describes a docstring subtree consisting of a string valued identifier and a list of free-form description lines: str, List[str]
Contract	general Must accept a list of parameter entries.
Parameters	tr The tracer for collecting diagnostics. entries A docstring subtree representing a list of parameter entries.
Returns	Must return None.
Raises	RuntimeError Must raise if parsing the sequence of parameter entries fails.
Method	docitem_parameters.parse

11.1.15.4. docitem_raises_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent an exception entry in the Raises section. Must accept and store a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse the content of an exception entry.
Class	docitem_raises_entry

Public Methods in class docitem_raises_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.15.5. docitem_raises

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Raises section. Must accept and store a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse a list of exceptions
Class	docitem_raises

Public Methods in class docitem_raises

Signature	sdv.doc.waterloo.docitem_sections.docitem_raises.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Terminology	Exception entry Describes a docstring subtree consisting of a string valued qualified identifier and a list of free-form description lines: str, List[str]
Contract	general Must accept a sequence of exception entries.
Parameters	tr The tracer for collecting diagnostics. entries A sequence of exception entries,
Returns	Must return None.
Raises	RuntimeError Must raise if parsing fails.
Method	docitem_raises.parse

11.1.15.6. docitem_derived_from

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Derived_from section. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Parse a Derived_from section.
Class	docitem_derived_from

Public Methods in class docitem_derived_from

Signature	sdv.doc.waterloo.docitem_sections.docitem_derived_from.parse( tr: tracer bases: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must set rules-on-fail in the tracer and delegate to the base implementation. base sdv.doc.waterloo.docitem.docitem_base.parse
Inherited_method	docitem_derived_from.parse

11.1.15.7. docitem_factory_functions

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the content of an entry in section Factory. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of text lines describing the factory function.
Class	docitem_factory_functions

Public Methods in class docitem_factory_functions

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.15.8. docitem_factory

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Factory section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse a Factory.
Class	docitem_factory

Public Methods in class docitem_factory

Signature	sdv.doc.waterloo.docitem_sections.docitem_factory.parse( tr: tracer functions: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of section Factory.
Parameters	tr The tracer for collecting diagnostics. functions The docstring subtree to parse, a list of factory function sections.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a set of factory function sections. In detail: Must raise if the content is not a sequence of pairs label / list of strings.
Method	docitem_factory.parse

11.1.15.9. docitem_definitions_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent an entry in the Definitions section. Must accept and store a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse the content of an definition entry.
Class	docitem_definitions_entry

Public Methods in class docitem_definitions_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.15.10. docitem_inherited_defitems

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the special entry in the Definitions section. Must accept and store a list of identifiers. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Parse the content of an inherited defitem.
Class	docitem_inherited_defitems

Public Methods in class docitem_inherited_defitems

11.1.15.11. docitem_definitions

Preamble	normative sections Contract, Public methods
Contract	general Must represent a definition enrty. Must accept and store a map from str to docitem_base. constructor Must be default-constructible
Public methods	parse
Method overview	parse Parse a sequence of definition entries
Class	docitem_definitions

Public Methods in class docitem_definitions

Signature	sdv.doc.waterloo.docitem_sections.docitem_definitions.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must accept a sequence of definition entries.
Parameters	tr The tracer for collecting diagnostics. entries A sequence of definition entries.
Returns	Must return None.
Raises	RuntimeError Must raise if parsing fails.
Method	docitem_definitions.parse

11.1.15.12. docitem_terminology_entry

Preamble	normative sections Contract, Derived from, Public methods
Terminology	Terminology entry Describes a docstring subtree consisting of a string valued qualified identifier and a list of free-form description lines: str, List[str]
Contract	general Must represent an entry in the Terminology section. Must accept and store a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse the content of an terminology entry.
Class	docitem_terminology_entry

Public Methods in class docitem_terminology_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.15.13. docitem_terminology

Preamble	normative sections Contract, Public methods
Description	A Terminology section describes natural language expressions informatively. As opposed to a Definitions section, it is never normative and does not contain normativity keywords.
Contract	general Must represent a terminology enrty. Must accept and store a map from str to docitem_base. constructor Must be default-constructible
Public methods	parse
Method overview	parse Parse a sequence of terminology entries
Class	docitem_terminology

Public Methods in class docitem_terminology

Signature	sdv.doc.waterloo.docitem_sections.docitem_terminology.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must accept a sequence of terminology entries.
Parameters	tr The tracer for collecting diagnostics. entries A sequence of terminology entries.
Returns	Must return None.
Raises	RuntimeError Must raise if parsing fails.
Method	docitem_terminology.parse

11.1.15.14. docitem_description

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must hold free-form descriptive text lines from a docstring section Description. Must accept and store a list of strings. constructor Must be default-constructible.
Description	A free-form section which informatively describes the purpose of a module, class or callable.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of description lines.
Class	docitem_description

Public Methods in class docitem_description

Signature	sdv.doc.waterloo.docitem_sections.docitem_description.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must accept a list of description lines. Must raise if the input is not a list of strings.
Parameters	tr The tracer for collecting diagnostics. lines The description lines.
Returns	Must return None.
Raises	RuntimeError Must raise if validation fails.
Method	docitem_description.parse

11.1.15.15. docitem_notes_entry

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the content of an entry in section Notes. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_free_text_entry_base
Public methods	parse
Method overview	parse Parse a list of text lines of the note.
Class	docitem_notes_entry

Public Methods in class docitem_notes_entry

Signature	sdv.doc.waterloo.docitem_base.docitem_free_text_entry_base.parse( tr: tracer lines: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must parse the content of an entry in section Class_overview, Public_types, Public_constants, Method_overview, Function_overview, Parameters, Raises, Definitions, Terminology.
Parameters	tr The tracer for collecting diagnostics. lines The docstring subtree to parse, a list of free-form strings representing the content of any of the sections listet in section Contract.General.
Returns	Must return None.
Raises	RuntimeError Must raise if the content is not a list of strings.
Method	docitem_free_text_entry_base.parse

11.1.15.16. docitem_notes

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the Notes section. Must be able to hold a map from str to docitem_base. constructor Must be default-constructible.
Derived from	docitem_map_base
Public methods	parse
Method overview	parse Parse the content of a section Notes.
Class	docitem_notes

Public Methods in class docitem_notes

Signature	sdv.doc.waterloo.docitem_sections.docitem_notes.parse( tr: tracer entries: DocstringSubtree ) -> None
Preamble	normative sections Contract, Parameters, Returns, Raises
Terminology	Labelled note A labelled note in this context is a pair str, List[str].
Contract	general Must parse a sequence of labelled notes. Must interpret a missing list in a labelled note as an empty list.
Parameters	tr The tracer for collecting diagnostics. entries The docstring subtree to parse, a sequence of labelled notes, like [str, List, str, List,…].
Returns	Must return None.
Raises	RuntimeError Must raise if the content cannot be interpreted as a sequence of labelled notes.
Method	docitem_notes.parse

11.1.15.17. docitem_see_also

Preamble	normative sections Contract, Derived from, Public methods
Contract	general Must represent the See_also section. Must be able to hold a list of strings. constructor Must be default-constructible.
Derived from	docitem_list_of_symbols_base
Public methods	parse
Method overview	parse Inherited method
Class	docitem_see_also

Public Methods in class docitem_see_also

Signature	sdv.doc.waterloo.docitem_sections.docitem_see_also.parse( tr: tracer refs: DocstringSubtree ) -> None
Preamble	normative sections Contract
Contract	general Must set rules-on-fail in the tracer and delegate to the base implementation. base sdv.doc.waterloo.docitem.docitem_base.parse
Inherited_method	docitem_see_also.parse

11.1.16. Top-level node classes

11.1.16.1. docitem_docstring_module

Preamble	normative sections Contract, Factory, Derived from, Public methods
Contract	general Must represent the docstring for profile module. Must provide a map from str to Type[docitem_base] which assigns a docitem class constructor to each allowed section label. constructor Must be default-constructible
Factory	make_docitem_tree Must accept a tracer and a docstring, read the profile and generate the AST from it. See docstring of function.
Derived from	docitem_docstring_base
Public methods	dispatch_map
Method overview	dispatch_map Return the forementioned map from label to constructor.
Class	docitem_docstring_module

Public Methods in class docitem_docstring_module

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_module.dispatch_map( ) -> Dict[str, Type[docitem_base]]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must return a map from the set of allowed section labels (including the trailing colon) to the constructor of the class representing the section. Must provide label/constructor pairs for at least the folowing sections: { Preamble, Definitions, Terminology, Contract, Description, Function_overview, Class_overview, Public_types, Public_constants}
Parameters
Returns	The dict as described in Contract.
Raises	<empty>
Method	docitem_docstring_module.dispatch_map

11.1.16.2. docitem_docstring_class

Preamble	normative sections Contract, Factory, Derived from, Public methods
Contract	general Must represent the docstring for profiles class. Must provide a map from str to Type[docitem_base] which assigns a docitem class constructor to each allowed section label. constructor Must be default-constructible
Factory	make_docitem_tree Must accept a tracer and a docstring, read the profile and generate the AST from it. See docstring of function.
Derived from	docitem_docstring_base
Public methods	dispatch_map
Method overview	dispatch_map Return the forementioned map from label to constructor.
Class	docitem_docstring_class

Public Methods in class docitem_docstring_class

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_class.dispatch_map( ) -> Dict[str, Type[docitem_base]]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must return a map from the set of allowed section labels (including the trailing colon) to the constructor of the class representing the section. Must provide label/constructor pairs for at least the folowing sections: { Preamble, Definitions, Terminology, Contract, Derived_from, Factory, Description, Class_overview, Method_overview, Public_types, Public_constants}
Parameters
Returns	The dict as described in Contract.
Raises	<empty>
Method	docitem_docstring_class.dispatch_map

11.1.16.3. docitem_docstring_method

Preamble	normative sections Contract, Factory, Derived from, Public methods
Contract	general Must represent the docstring for profiles function and method. Must provide a map from str to Type[docitem_base] which assigns a docitem class constructor to each allowed section label. constructor Must be default-constructible
Factory	make_docitem_tree Must accept a tracer and a docstring, read the profile and generate the AST from it. See docstring of function.
Derived from	docitem_docstring_base
Public methods	dispatch_map
Method overview	dispatch_map Return the forementioned map from label to constructor.
Class	docitem_docstring_method

Public Methods in class docitem_docstring_method

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_method.dispatch_map( ) -> Dict[str, Type[docitem_base]]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must return a map from the set of allowed section labels (including the trailing colon) to the constructor of the class representing the section. Must provide label/constructor pairs for at least the folowing sections: { Preamble, Definitions, Terminology, Contract, Parameters, Returns, Raises, Description}
Parameters
Returns	The dict as described in Contract.
Raises	<empty>
Method	docitem_docstring_method.dispatch_map

11.1.16.4. docitem_docstring_inherited_method

Preamble	normative sections Contract, Factory, Derived from, Public methods
Contract	general Must represent the docstring for profile inherited_method. Must provide a map from str to Type[docitem_base] which assigns a docitem class constructor to each allowed section label. constructor Must be default-constructible
Factory	make_docitem_tree Must accept a tracer and a docstring, read the profile and generate the AST from it. See docstring of function.
Derived from	docitem_docstring_base
Public methods	dispatch_map
Method overview	dispatch_map Return the forementioned map from label to constructor.
Class	docitem_docstring_inherited_method

Public Methods in class docitem_docstring_inherited_method

Signature	sdv.doc.waterloo.docitem_docstring.docitem_docstring_inherited_method.dispatch_map( ) -> Dict[str, Type[docitem_base]]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must return a map from the set of allowed section labels (including the trailing colon) to the constructor of the class representing the section. Must provide label/constructor pairs for at least the folowing sections: { Preamble, Definitions, Terminology, Contract, Parameters, Returns, Raises, Description}
Parameters
Returns	The dict as described in Contract.
Raises	<empty>
Method	docitem_docstring_inherited_method.dispatch_map

11.1.17. Factories

11.1.17.1. make_docitem_tree

Signature	sdv.doc.waterloo.docitem_docstring.make_docitem_tree( tr: tracer doc_txt: str ) -> docitem_docstring_base
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must accept a tracer instance and a string as parameters. Must try to parse the string as waterloo docstring and create a docstring tree. Must determine the profile from the docstring tree and create the appropriate docitem node class. Must call the docitem node’s method parse and create an Abstract Syntax Tree.
Parameters	tr The tracer for collecting diagnostics. doc_txt The docstring to parse
Returns	Must return the docitem node instance containing the AST
Raises	ParseError Must raise if docstring is empty. Must raise if section Preamble is not found. Must raise if subsection Preamble.profile is not found. Must raise if subsection Preamble.profile does not contain exactly one item. Must raise if the content of subsection Preamble.profile is not an identifier.. Must raise if subsection Preamble.profile does not contain a valid profile. BaseException Must not propagate exceptions from get_profile_of_tree. May propagate exceptions from method parse_indent_docstring. May propagate exceptions from method docitem_docstring_base. parse.
Notes	Last review 2026-01-22
Function	make_docitem_tree

Default module qualifier sdv.doc.waterloo.docitem ends here. New default: sdv.doc.waterloo.

11.2. Module docitem_sphinx

Preamble	normative sections Contract, Public classes, Public functions
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
Class overview	context Internal class, please ignore
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
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::
Module	sdv.doc.waterloo.docitem_sphinx

11.2.1. Functions

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

11.2.1.1. build_sphinx_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.build_sphinx_nodes( ctx: context obj: object doc: mod_docitem.docitem_docstring_base ) -> List[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must convert a parsed docitem_docstring_module, docitem_docstring_class or docitem_docstring_method into a list of docutils nodes. Must render section/key/value content into a two-column table with section labels on the left and content on the right. Must apply role-formatters provided by context (labels, types, vars, funcs, methods). Must assign a deterministic anchor id to the rendered table. Must render selected reference-like entries as internal links where targets can be resolved. Must keep unresolved reference entries visible as plain text fallback. 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 inline parser and role-formatters. obj The documented object (module, class or method). doc Parsed docstring tree (representing one of the defined profiles).
Returns	List of docutils.nodes.Node representing the rendered documentation table.
Raises	RuntimeError May raise if unexpected section structure is encountered. 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. Linking Internal links are created using anchor ids from build_anchor. Built-in exceptions in section Raises are intentionally rendered as plain text without internal links. Last review 2026-02-15
Function	build_sphinx_nodes

11.2.1.2. build_sphinx_nodes_full

Signature	sdv.doc.waterloo.docitem_sphinx.build_sphinx_nodes_full( ctx: context class_obj: Any session: mod_docitem.DocSession ) -> List[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must analyze the docstring and methods of the class object. Must create a list of sphinx nodes, with elements as specified in the following and have the order as indicated: The list must contain nodes representing the class’ docstring. The list must contain nodes produced by ctx.build_prolog_method_overview. For each public method as indicated by the class’ normative docstring: 1. The list must contain nodes produced by ctx.build_prolog_method_block. 2. The list must contain nodes representing the class’ public method’s docstring.
Parameters	ctx The context class_obj The class object to generate a sphinx documentation node list from. session An object to store state and cache information across multiple calls to this function.
Returns	A list of sphinx nodes representing the class and public member documentation.
Raises	RuntimeError Must raise if something goes wrong parsing a docstring. BaseException Must forward exceptions from Sphinx
Function	build_sphinx_nodes_full

11.2.1.3. resolve_qualified_name

Signature	sdv.doc.waterloo.docitem_sphinx.resolve_qualified_name( ctx: context | None qname: str ) -> tuple[object, str, str, list[str]]
Preamble	normative sections Contract, Parameters, Returns, Raises
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

11.2.2. Directives for docstring rendering

11.2.2.1. wtrl_build_autodoc_module_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.wtrl_build_autodoc_module_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must resolve the dotted module name text to a Python module object taking into account the current module state. Must parse and validate the module’s Waterloo docstring. Must render the parsed docstring into Docutils nodes using the configured context.
Description	Implementation of role :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	The list of generated docutils.nodes.Node representing the module doumentation.
Raises	RuntimeError Must raise if the qualified name cannot be resolved Must raise if parsing the docstring fails. Must raise if validating the docstring tree fails BaseException May raise if building the list of Docutils nodes fails.
Function	wtrl_build_autodoc_module_nodes

11.2.2.2. wtrl_build_autodoc_function_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.wtrl_build_autodoc_function_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must resolve the dotted function name qname to a callable taking into account the current module/class state. Must parse and validate the function’s Waterloo docstring. Must render the parsed docstring into Docutils nodes using the configured context.
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.
Raises	RuntimeError Must raise if the qualified name cannot be resolved. Must raise if parsing the docstring fails. Must raise if validating the docstring tree fails. BaseException May raise if building the list of Docutils nodes fails.
Function	wtrl_build_autodoc_function_nodes

11.2.2.3. wtrl_build_autodoc_class_full_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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
Contract	general Must parse the class’s docstring and create a docstring tree. Must parse the class methods’ docstrings and create docstring trees. Must validate the docstring trees. Must convert the docstring trees into a list of Docutils nodes that represent the docstrings.
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.
Raises	RuntimeError Must raise if the qualified name cannot be resolved. Must raise if parsing of any of the docstrings fails. Must raise if validating the docstring tree fails. BaseException May raise if building the list of Docutils nodes fails.
Function	wtrl_build_autodoc_class_full_nodes

11.2.2.4. wtrl_build_autodoc_class_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.wtrl_build_autodoc_class_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must resolve the dotted class name qname to a class taking into account the current module/class state. Must parse and validate the class’ Waterloo docstring. Must render the parsed docstring into Docutils nodes using the configured context.
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.
Raises	RuntimeError Must raise if the qualified name cannot be resolved. Must raise if parsing the docstring fails. Must raise if validating the docstring tree fails. BaseException May raise if building the list of Docutils nodes fails.
Function	wtrl_build_autodoc_class_nodes

11.2.3. Directives for setting default module and class

11.2.3.1. wtrl_build_push_current_module_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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
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.
Notes	Last review 2026-02-04
Function	wtrl_build_push_current_module_nodes

11.2.3.2. wtrl_build_push_current_class_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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
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.
Notes	Last review 2026-02-04
Function	wtrl_build_push_current_class_nodes

11.2.3.3. wtrl_build_push_current_scope_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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
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.
Notes	Last review 2026-02-04
Function	wtrl_build_push_current_scope_nodes

11.2.3.4. wtrl_build_pop_current_module_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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
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 qname does not resolve to a module. BaseException May propagate exceptions from resolve_qualified_name. May propagate exceptions from within Sphinx or Docutils.
Notes	Last review 2026-02-04
Function	wtrl_build_pop_current_module_nodes

11.2.3.5. wtrl_build_pop_current_class_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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
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 qname does not resolve to a class. BaseException May propagate exceptions from resolve_qualified_name. May propagate exceptions from within Sphinx or Docutils.
Notes	Last review 2026-02-04
Function	wtrl_build_pop_current_class_nodes

11.2.3.6. wtrl_build_pop_current_scope_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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
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 scope_tag is unknown or mismatches the stack top. BaseException May propagate exceptions from within Sphinx or Docutils.
Notes	Last review 2026-02-04
Function	wtrl_build_pop_current_scope_nodes

11.2.4. Directives for expanding callable signatures

11.2.4.1. wtrl_build_method_signature_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.wtrl_build_method_signature_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope core
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.
Notes	Last review 2026-02-04
Function	wtrl_build_method_signature_nodes

11.2.4.2. wtrl_build_function_signature_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.wtrl_build_function_signature_nodes( app: SphinxAppProtocol | Any inliner: InlinerProtocol lineno: int qname: str ) -> list[nodes.Node]
Preamble	normative sections Contract, Parameters, Returns, Raises scope core
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 method to render.
Returns	The list of generated docutils.nodes.Node describing the function signature.
Raises	BaseException May propagate exceptions from docutils.
Notes	Last review 2026-02-04
Function	wtrl_build_function_signature_nodes

11.2.4.3. wtrl_build_method_signature_block_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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 scope core
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.
Notes	Last review 2026-02-04
Function	wtrl_build_method_signature_block_nodes

11.2.4.4. wtrl_build_function_signature_block_nodes

Signature	sdv.doc.waterloo.docitem_sphinx.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 scope core
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 method to render.
Returns	The list of generated docutils.nodes.Node describing the function signature.
Raises	BaseException May propagate exceptions from docutils.
Notes	Last review 2026-02-04
Function	wtrl_build_function_signature_block_nodes

Default module qualifier sdv.doc.waterloo.docitem_sphinx ends here. New default: sdv.doc.waterloo.

11.3. Module docitem_convert

Preamble	normative sections Contract, Public functions, Public types scope public
Contract	general Must provide converter functions for all flavours and formats in sdv.doc.waterloo.helper.
Public functions	to_node_legend_json, to_node_docstring_tree_json, to_node_signature_json, to_string_md, build_node_json
Public types	WtrlJsonNode_t Type for JSON nodes. This type must be public because to_node_docstring_tree_json and to_node_signature_json are.
Module	sdv.doc.waterloo.docitem_convert

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

11.3.1. Converter functions

11.3.1.1. to_node_legend_json

Signature	sdv.doc.waterloo.docitem_convert.to_node_legend_json( ) -> Dict[str, WtrlJsonNode_t]
Preamble	normative sections Contract, Parameters, Returns, Raises scope public status stable
Contract	general Must return a JSON-serializable mapping from Waterloo role names to short descriptions.
Parameters
Returns	Mapping of role-name -> human-readable description.
Raises	<empty>
Function	to_node_legend_json

11.3.1.2. to_node_docstring_tree_json

Signature	sdv.doc.waterloo.docitem_convert.to_node_docstring_tree_json( tree: DocstringTree flavour: Flavour ) -> WtrlJsonNode_t
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope public status experimental
Contract	general Must render the tree as JSON-Node using the given flavour. Must reproduce the tree structure by appropriate subobjects in JSON. In RFC_2199 flavour, Normativity Keywords must be capitalized and the pipe delimiters must be dropped. In RAW flavour, Normativity Keywords must be rendered without modification, i.e. including pipe delimiters. In MARKUP flavour, Normativity Keywords must be rendered with double asterisk **...** instead of pipe delimiters. requires tree must be a formally correct docstring tree.
Notes	Details The docstring tree is rendered exactly as nested JSON arrays; no additional restructuring is performed.
Parameters	tree The tree to render as string. flavour The style to render Normativity Keywords in
Returns	The JSON node
Raises	ParseError Must propagate from make_docitem_tree_from_docstring_tree. BaseException May propagate from make_docitem_tree_from_docstring_tree. May propagate from nested function calls.
See also	sdv.doc.waterloo.docitem.Flavour, sdv.doc.waterloo.docitem.Format
Function	to_node_docstring_tree_json

11.3.1.3. to_node_signature_json

Signature	sdv.doc.waterloo.docitem_convert.to_node_signature_json( obj: object ) -> dict[str, WtrlJsonNode_t]
Preamble	normative sections Contract, Parameters, Returns, Raises scope public status experimental
Contract	general Must render a JSON object as configured in config, representing the signature of the callable obj. The root property must be signature. This object must contain the keys text, parameters, and returns. text must be a string representation of the signature. parameters must be an array of objects, each containing: name: The parameter identifier string. kind: The Python parameter mode as a string constant. annotation: The type hint string or null. default: The default value as a string or null. The key returns must represent the return type.
Parameters	obj The callable whose signature is to be inspected and rendered.
Returns	The generated JSON node
Raises	TypeError Must be raised if obj is not callable or if the signature cannot be inspected. ValueError May be raised if the signature includes parameter kinds that cannot be serialized. Exception May propagate exceptions from inspect.signature or repr during default value rendering; callers should treat these as unexpected errors.
Notes	Standard values for “kind” Derived from inspect.Parameter: POSITIONAL_ONLY, POSITIONAL_OR_KEYWORD, VAR_POSITIONAL, KEYWORD_ONLY, VAR_KEYWORD
Function	to_node_signature_json

11.3.1.4. build_node_json

Signature	sdv.doc.waterloo.docitem_convert.build_node_json( node_docstring: docitem_docstring_base flavour: Flavour ) -> WtrlJsonNode_t
Preamble	normative sections Contract, Parameters, Returns, Raises scope public status experimental
Contract	general Must build a JSON node from the Abstract Syntax Tree node_docstring. Must convert Normativity Keywords in free-form text according to the given flavour. requires node_docstring must be a formatlly correct AST node representing the docstring item of a module, class, function, method, or inherited method.
Parameters	node_docstring The AST node flavour Normativity Keyword style.
Returns	The JSON node, a dict in our case, which represents the AST node.
Raises	NotImplementedError May raise in case node_docstring has some unexpected type. BaseException May propagate from underlying modules such as re.
Function	build_node_json

11.3.1.5. to_string_md

Signature	sdv.doc.waterloo.docitem_convert.to_string_md( tree: DocstringTree flavour: Flavour = <Flavour.MARKDOWN: 2> headings: bool = True ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises, See also scope public status draft
Contract	general Must render the tree as Markdown using the given flavour (default: MARKDOWN). Must preserve the sequence structure as nested unordered lists. Must render normativity tokens according to flavour (e.g. MUST for MARKDOWN). requires tree must be a formally correct docstring tree.
Parameters	tree The docstring tree to render. flavour The formatting style for normativity tokens. headings If True, section-like items (strings ending with ‘:’ that precede a list) are rendered as Markdown headings instead of plain bullets.
Returns	A Markdown string.
Raises	TypeError Must raise if tree is not a sequence made only of strings and lists, or if flavour is not a Flavour.
See also	sdv.doc.waterloo.docitem.Flavour, sdv.doc.waterloo.docitem.Format
Function	to_string_md

Default module qualifier sdv.doc.waterloo.docitem_convert ends here. New default: sdv.doc.waterloo.

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

11.4. Module docitem_genutil

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

Preamble	normative sections Contract, Public functions scope extension
Contract	general Must provide functions for generating minimal and full waterloo docstring templates. Must represent the Single Source of Truth for the structure and content of these templates. Should represent the Single Source of Truth for future cuts of such templates. Must provide JSON representations of these templates as a result from a canonical generation process (e.g. a script) in order to avoid drift.
Description	This module is intended for IDE-extension workflows. A typical use case is a VSCode context-menu action on a class or def line: parse the selected header fragment, infer/select a profile, and generate a minimal or full Waterloo docstring template. The signature-to-AST bridge in parse_signature_fragment is shared by MCP and IDE workflows. Keep it close to the AST-based generators so that the template text and any future JSON snippets continue to derive from the same canonical structure.
Public functions	parse_source_fragment, infer_docstring_profile, parse_signature_fragment, generate_minimal_docstring, generate_full_docstring, generate_minimal_docstring_from_node, generate_full_docstring_from_node
Notes	Important JSON templates for minimal and full docstring templates can be generated by means of $MAIN/tools/make_docstring_templates_json.sh. This script should be used in order to avoid drift. It represents the canonical generation process for these templates, and the resulting JSON files are the Single Source of Truth for their structure and content. Any future JSON snippets produced from signature fragments should stay aligned with the same canonical structure in package_main/templates-json/out.
Module	sdv.doc.waterloo.docitem_genutil

11.4.1. parse_source_fragment

Signature	sdv.doc.waterloo.docitem_genutil.parse_source_fragment( profile: Profile source_fragment: str ) -> ast.AST | None
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must return None if profile is module. Must parse source_fragment via ast. Must return the first top-level AST node from the parsed tree. Must ensure the returned node matches profile: For class, the node must be ast.ClassDef. For function, method, or inherited_method, the node must be ast.FunctionDef or ast.AsyncFunctionDef. Must reject empty parses (no top-level nodes).
Parameters	profile Profile used for node-type validation. source_fragment Source fragment containing a class/function/method header (or small stub). Ignored if profile is module.
Returns	None for profile module, otherwise the validated first AST node.
Raises	SyntaxError May be raised by ast.parse for invalid Python syntax. RuntimeError Must raise if no top-level node exists after parsing. Must raise if the parsed node type does not match profile.
Function	parse_source_fragment

11.4.2. infer_docstring_profile

Signature	sdv.doc.waterloo.docitem_genutil.infer_docstring_profile( obj: object ) -> Profile
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must derive the best matching waterloo docstring profile from the object.
Parameters	obj Object to inspect.
Returns
Raises	RuntimeError Must raise if obj does not match any of the categories module, class, callable.
Notes	Result The inherited_method profile is never returned because it does not differ from the method profile based solely on formal criteria.
Function	infer_docstring_profile

11.4.3. generate_minimal_docstring

Signature	sdv.doc.waterloo.docitem_genutil.generate_minimal_docstring( obj: object profile: Profile | None = None ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises status stable scope extension
Contract	general Must generate a minimal Waterloo docstring template for obj. Must select the template by using profile if provided. Must infer the profile from obj if profile is None. ensures The resulting template must be structurally valid according to the Waterloo format.
Parameters	obj Object for which the docstring template is generated. profile Optional explicit profile (module, class, function, method). If None, the profile is inferred from obj.
Returns	Generated minimal docstring template.
Raises	RuntimeError May be raised if profile inference fails for obj.
Function	generate_minimal_docstring

11.4.4. generate_full_docstring

Signature	sdv.doc.waterloo.docitem_genutil.generate_full_docstring( obj: object profile: Profile | None = None ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises status stable scope extension
Contract	general Must generate a full Waterloo docstring template for obj. Must include the extended section set for the resolved profile. Must select the template by using profile if provided. Must infer the profile from obj if profile is None. ensures The resulting template must be structurally valid according to the Waterloo format.
Parameters	obj Object for which the docstring template is generated. profile Optional explicit profile (module, class, function, method). If None, the profile is inferred from obj.
Returns	Generated full docstring template.
Raises	RuntimeError May be raised if profile inference fails for obj.
Function	generate_full_docstring

11.4.5. generate_minimal_docstring_from_node

Signature	sdv.doc.waterloo.docitem_genutil.generate_minimal_docstring_from_node( profile: Profile node: ast.AST | None ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises status stable scope extension
Contract	general Must generate a minimal Waterloo docstring template from a pre-parsed AST node. Must use profile to select the target template variant. Must ignore node if profile is module or class. Must require a function-like AST node for profiles function and method.
Parameters	profile Target profile (module, class, function, method). node Parsed AST node for function/method generation. May be None for profile module.
Returns	Generated minimal docstring template.
Raises	RuntimeError Must be raised if function/method generation is requested with an incompatible AST node.
Function	generate_minimal_docstring_from_node

11.4.6. generate_full_docstring_from_node

Signature	sdv.doc.waterloo.docitem_genutil.generate_full_docstring_from_node( profile: Profile node: ast.AST | None ) -> str
Preamble	normative sections Contract, Parameters, Returns, Raises status stable scope extension
Contract	general Must generate a full Waterloo docstring template from a pre-parsed AST node. Must use profile to select the target template variant. Must ignore node if profile is module or class. Must require a function-like AST node for profiles function and method.
Parameters	profile Target profile (module, class, function, method). node Parsed AST node for function/method generation. May be None for profile module.
Returns	Generated full docstring template.
Raises	RuntimeError Must be raised if function/method generation is requested with an incompatible AST node.
Function	generate_full_docstring_from_node

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

11.5. Pygments Lexer

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

Preamble	normative sections Contract, Definitions, Public classes, Public constants
Definitions	Pos_Role_Substring_Triple A tuple (position, token_type, substring) specifying syntax highlighting: position: The starting index of the substring in the original text. token_type: A Pygments token class (from pygments.token). substring: The text to be highlighted.
Contract	general Must provide a Python module that defines the PythonWaterlooLexer class for syntax highlighting of Waterloo-docstrings.
Public classes	PythonWaterlooLexer
Public constants	RE_SECTION_ALLOWED_NORMATIVE A regular expression pattern that matches section names allowed or mandatory in the “normative_sections” subsection of the Preamble. This expression is governed by the normative rules and must be kept up to date. Mandatory : CON-002, CON-005, CON-020, CON-034, CPCL-002, CPCON-002, CPMT-002, CPTYP-002, CPVAR-002, DEF-002, DER-004, FAC-009, MPCL-002, MPCON-002, MPFN-002, MPTYP-002, MPVAR-002, PAR-002, RAI-002, RET-002. Accepted : DESC-002, SEE-011. Refused : NOTE-002, PRE-002, TERM-002.
Module	python_waterloo_lexer

11.5.1. PythonWaterlooLexer

Preamble	normative sections Contract, Public methods
Contract	general Must implement a Pygments lexer class that extends the standard Python lexer to provide syntax highlighting for Waterloo-docstrings. Must define a static method analyse_text that checks if a given string looks like a Waterloo-docstring, returning a float score for lexer selection. Must implement the get_tokens_unprocessed method to yield tokens with appropriate types for different parts of the docstring, such as section headers, normative keywords, and inline markup. Must use regular expressions to identify section headers and inline markup patterns. Must ensure that the lexer can be used with Pygments for syntax highlighting in various tools and editors. Must prioritize this lexer over the standard Python lexer when the input text contains Waterloo-docstring patterns. Must handle edge cases gracefully, such as docstrings that do not conform to the expected structure or contain mixed indentation. Must include comprehensive comments and documentation within the code to explain the implementation and usage of the lexer. Must be implemented in a way that allows for easy maintenance and extension in the future, such as adding support for new sections or inline markup patterns. constructor default
Public methods	highlight_docstring, highlight_line, looks_like_waterloo_docstring, has_mixed_indentation, analyse_text, get_tokens_unprocessed
Class	PythonWaterlooLexer

Public Methods in class PythonWaterlooLexer

Signature	python_waterloo_lexer.PythonWaterlooLexer.highlight_docstring( base: int text: str ) -> Iterable[tuple[int, object, str]]
Preamble	normative sections Definitions, Contract, Parameters, Returns, Raises
Definitions	<Terms inherited from module> Pos_Role_Substring_Triple
Contract	general Must check if the given text looks like a Waterloo-docstring. Must if it does not look like a Waterloo-docstring, yield the entire text as a single String.Doc token. Must if it looks like a Waterloo-docstring, reset the parser state and analyze the text line by line. Must for each line, call the highlight_line method to identify and yield tokens for that line.
Parameters	base The base index for token positions in the original text. text The docstring text to analyze and tokenize.
Returns	An iterable of Pos_Role_Substring_Triple tuples for the given docstring.
Raises	BaseException May propagate exceptions from the re module. May propagate exceptions from the pygments module.
Method	PythonWaterlooLexer.highlight_docstring

Signature	python_waterloo_lexer.PythonWaterlooLexer.highlight_line( base: int line: str ) -> Iterable[tuple[int, object, str]]
Preamble	normative sections Definitions, Contract, Parameters, Returns, Raises
Definitions	<Terms inherited from module> Pos_Role_Substring_Triple
Contract	general Must analyze the given line in the context of the current section and subsection. Must identify section headers and update the current section state. Must identify subsection headers if the current section allows subsections, and update the current subsection state. Must identify special markers such as text flow markers and apply appropriate token types. Must apply specific tokenization rules based on the current section and subsection, such as treating certain lines as lists of identifiers or free-form text. Must yield tokens with appropriate types for the identified elements in the line.
Parameters	base The base index for token positions in the original text. line The line of text to analyze and tokenize.
Returns	An iterable of Pos_Role_Substring_Triple tuples for the given line.
Raises	BaseException May propagate exceptions from the re module.
Method	PythonWaterlooLexer.highlight_line

Signature	@staticmethod python_waterloo_lexer.PythonWaterlooLexer.looks_like_waterloo_docstring( text: str ) -> bool
Preamble	normative sections Contract, Parameters, Returns, Raises scope core
Description	This method performs a heuristic analysis of the input text to determine if it resembles a Waterloo-docstring. For a full and exact validation use the tool waterlint instead, which implements the complete set of normative rules for Waterloo-docstrings.
Contract	general Must look for the presence of a Preamble and Contract section (PRE-001, CON-001). Must check that the section labels match the expected format (PRSR-001, PRSR-002, PRSR-003, PRSR-004, PRSR-005). Must check that the Preamble and Contract sections appear in the correct order (PRE-001). Must check that there is no mixed indentation in the docstring (TKN-003).
Parameters	text The string to analyze
Returns	True if the string looks like a Waterloo docstring, False otherwise.
Raises	BaseException May propagate from module re.
Method	PythonWaterlooLexer.looks_like_waterloo_docstring

Signature	@staticmethod python_waterloo_lexer.PythonWaterlooLexer.has_mixed_indentation( text: str ) -> bool
Preamble	normative sections Contract, Parameters, Returns, Raises
Contract	general Must check for the presence of mixed indentation in the text. Must consider a line to have mixed indentation if it contains both tabs and spaces in the leading whitespace. Must consider the text to have mixed indentation if there are some lines that use tabs for indentation and some lines that use spaces, even if no individual line has mixed indentation.
Parameters	text The string to analyze for mixed indentation.
Returns	True if the text has mixed indentation, False otherwise.
Raises	BaseException May propagate from module re. May propagate from module sys.
Method	PythonWaterlooLexer.has_mixed_indentation

Signature	pygments.util.make_analysator.<locals>.text_analyse( text: Any ) -> Any
Preamble	normative sections Contract, Parameters, Returns, Raises
Description	This method is called by Pygments during lexer selection to prioritize the PythonWaterlooLexer over the standard PythonLexer. It analyzes the input text for patterns indicative of Waterloo-docstrings, such as the presence of “Preamble:” and “Contract:” sections, ensuring that files containing structured docstrings are highlighted appropriately by this specialized lexer.
Contract	general Must determine if the given text resembles a Waterloo-docstring. Must perform a quick check for presence of “Preamble:” and “Contract:”. Must conduct a detailed line-by-line validation using regex patterns. Must return 1.0 if both sections are properly matched, otherwise 0.0.
Parameters	text The input text to analyze for Waterloo-docstring characteristics.
Returns	A float value: 1.0 if the text is identified as a Waterloo-docstring, 0.0 otherwise.
Raises	BaseException May propagate exceptions from the re module.
Function	make_analysator.<locals>.text_analyse

Signature	python_waterloo_lexer.PythonWaterlooLexer.get_tokens_unprocessed( text: str ) -> Iterator[tuple[int, object, str]]
Preamble	normative sections Contract, Definitions, Parameters, Returns, Raises scope extension
Definitions	<Terms inherited from module> Pos_Role_Substring_Triple
Description	This is the core tokenization method that Pygments calls to obtain syntax highlighting tokens. It iterates over tokens from the parent PythonLexer and intercepts docstrings (String.Doc tokens) to apply Waterloo-specific highlighting rules. This method is the entry point for all tokenization and determines the highlighting of the entire source code.
Contract	general Must analyze the provided string. Must iterate over the input lines to identify Waterloo-specific tokens. Must generate a Pos_Role_Substring_Triple for each matching token. Must fall back to default highlighting for non-matching docstring parts.
Parameters	text The input text to tokenize.
Returns	An iterable of Pos_Role_Substring_Triple tuples.
Raises	BaseException May propagate from the pygments module.
Method	PythonWaterlooLexer.get_tokens_unprocessed

Default module qualifier python_waterloo_lexer ends here. No default module active.

11.6. Output layer HTML5

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

Preamble	normative sections Contract, Public functions scope extension
Contract	general Must provide a function render_html5 that serves as the main entry point for the waterlint render-html5 subcommand.
Public functions	render_html5, render_html5_document, build_parser
Function overview	render_html5 Main entry point for the waterlint render-html5 subcommand. This function takes in a list of input JSON document paths, merges them, and generates a self-contained HTML5 file that presents the documented objects in a clear and navigable format. The function also handles error reporting via the provided tracer instance and supports various customization options for the output HTML. render_html5_document Render a single HTML5 document from the merged JSON data. build_parser Construct and return the argparse subparser for the render-html5 command.
Module	sdv.doc.waterloo.waterlint_render_html5

Signature	sdv.doc.waterloo.waterlint_render_html5.render_html5( args: argparse.Namespace ) -> int
Preamble	normative sections Contract, Parameters, Returns, Raises scope extension
Contract	general Must execute the render-html5 command on one or more Waterloo JSON inputs and write the resulting HTML output.
Parameters	args Namespace containing the parsed render-html5 command line options. must provide the attributes expected by this command: input_files: one or more input groups as produced by repeated --in options; each group must contain one or more Waterloo JSON file paths. Exactly one of out_file or out_dir must be present and designate the HTML output target. fail_on_warning must be present, because the exit code depends on it. out_diag and out_diag_json may be present as optional tracer-diagnostics targets. css_file, additional_css_file, header_html_file, pygments_theme, no_render_preamble, and allow_raw_object_node may be present as rendering controls. debug may be present as a reserved global flag.
Returns	Must return 0 on success, non-zero on validation or processing errors.
Raises	<empty>
Function	render_html5

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

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