{ "$schema": "https://sci-d-vis.com/schema/wtrl-json-0.1.0.schema.json", "$id": "urn:waterlint:wtrl-json:0.22.0:core:rfc-2119:5e836bf6ab210456292641d5a679727267e1adaa5592e6ff8c49da303790c7a2", "__WTRL_VERSION__": { "waterloo": "0.12.12", "schema": "0.1.0" }, "__WTRL_META__": { "generated_at": "2026-07-31T09:28:41+02:00", "generator": "waterlint", "scope": "core", "flavour": "rfc-2119" }, "__WTRL_ROLES__": { "attr": "Attribute name", "cmd": "Shell or CLI command", "class": "Class name", "dfn": "Definition of a term", "file": "File or path", "func": "Function or callable", "key": "Key on the keyboard", "label": "Section/Subsection label", "lit": "Literal text or code", "mod": "Module name", "norm": "Normativity keyword used as metadata", "op": "Operator symbol", "opt": "Command-line option or flag", "pkg": "Package name", "url": "URL", "tag": "Tag or marker", "term": "Domain-specific term", "type": "Type name or annotation", "value": "Concrete value", "var": "Variable name", "var_type": "Variable and type, like 'var:type'" }, "__WTRL_SCOPES__": { "public": { "value": 10, "description": "" }, "extension": { "value": 20, "description": "" }, "core": { "value": 30, "description": "" } }, "__WTRL_TOC_MODULES__": { "sphinxcontrib.waterloo_docstrings.extension": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.extension", "sphinxcontrib.waterloo_docstrings.wtrl_context": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_context", "sphinxcontrib.waterloo_docstrings.wtrl_state": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state", "sphinxcontrib.waterloo_docstrings.wtrl_directives": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_directives", "sphinxcontrib.waterloo_docstrings.wtrl_markup": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_markup", "sphinxcontrib.waterloo_docstrings.wtrl_parse": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_parse", "sphinxcontrib.waterloo_docstrings.wtrl_roles": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_roles", "sphinxcontrib.waterloo_docstrings.wtrl_signature": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_signature", "sphinxcontrib.waterloo_docstrings.wtrl_autodoc": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_autodoc", "sphinxcontrib.waterloo_docstrings.wtrl_protocol": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_protocol" }, "__WTRL_TOC_CLASSES__": { "sphinxcontrib.waterloo_docstrings.wtrl_context.context": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_context.context", "sphinxcontrib.waterloo_docstrings.wtrl_directives.WtrlDirectiveBase": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_directives.WtrlDirectiveBase", "sphinxcontrib.waterloo_docstrings.wtrl_roles.RolePara": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_roles.RolePara", "sphinxcontrib.waterloo_docstrings.wtrl_protocol.InlinerProtocol": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_protocol.InlinerProtocol", "sphinxcontrib.waterloo_docstrings.wtrl_protocol.SphinxEnvProtocol": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_protocol.SphinxEnvProtocol", "sphinxcontrib.waterloo_docstrings.wtrl_protocol.SphinxAppProtocol": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_protocol.SphinxAppProtocol" }, "__WTRL_TOC_CALLABLES__": { "sphinxcontrib.waterloo_docstrings.wtrl_context.context.__init__": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_context.context.__init__", "sphinxcontrib.waterloo_docstrings.wtrl_context.make_context": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_context.make_context", "sphinxcontrib.waterloo_docstrings.wtrl_state.resolve_qualified_name": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.resolve_qualified_name", "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_module_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_module_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_class_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_class_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_scope_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_scope_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_module_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_module_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_class_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_class_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_scope_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_scope_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_state.is_target_obj_visible_in_current_scope": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_state.is_target_obj_visible_in_current_scope", "sphinxcontrib.waterloo_docstrings.wtrl_markup.resolve_markup": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_markup.resolve_markup", "sphinxcontrib.waterloo_docstrings.wtrl_parse.parse_inline": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_parse.parse_inline", "sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_attr_role": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_attr_role", "sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_var_type_role": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_var_type_role", "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_block_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_block_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_block_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_block_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes_full": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes_full", "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_module_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_module_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_function_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_function_nodes", "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_full_nodes": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_full_nodes" }, "__WTRL_TOC_TYPES__": { "sphinxcontrib.waterloo_docstrings.extension.ObjectOriginDisplayMode_t": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.extension.ObjectOriginDisplayMode_t", "sphinxcontrib.waterloo_docstrings.extension.RoleResult": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.extension.RoleResult" }, "__WTRL_TOC_VARIABLES__": {}, "__WTRL_TOC_CONSTANTS__": { "sphinxcontrib.waterloo_docstrings.extension.RST_TEXT_ESCAPE_CHARS": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.extension.RST_TEXT_ESCAPE_CHARS", "sphinxcontrib.waterloo_docstrings.extension.RST_ROLE_BODY_ESCAPE_CHARS": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.extension.RST_ROLE_BODY_ESCAPE_CHARS", "sphinxcontrib.waterloo_docstrings.extension.WTRL_TOKEN_REPLACEMENTS": "/__WTRL_OBJECTS__/sphinxcontrib.waterloo_docstrings.extension.WTRL_TOKEN_REPLACEMENTS" }, "__WTRL_OBJECTS__": { "sphinxcontrib.waterloo_docstrings.extension.ObjectOriginDisplayMode_t": { "doc": {}, "doc_lines": [ "Literal type for configuration variable |var|`wtrl_object_origin_display_mode`." ], "annotation": "Literal['omit', 'short', 'long']", "doc_lines_kind": "type" }, "sphinxcontrib.waterloo_docstrings.extension.RoleResult": { "doc": {}, "doc_lines": [ "Aggregate type for the return value of role handler functions. |type|`RoleResult` is a tuple of the form (nodes, messages) where nodes is a list of Docutils nodes and messages is a list of Docutils system messages." ], "annotation": "tuple[List[docutils.nodes.Node], list[docutils.nodes.Node]]", "doc_lines_kind": "type" }, "sphinxcontrib.waterloo_docstrings.extension.RST_TEXT_ESCAPE_CHARS": { "doc": {}, "doc_lines": [ "A |type|`frozenset` of characters escaped in reStructuredText text segments to avoid unintended markup interpretation." ], "doc_lines_kind": "constant" }, "sphinxcontrib.waterloo_docstrings.extension.RST_ROLE_BODY_ESCAPE_CHARS": { "doc": {}, "doc_lines": [ "A |type|`frozenset` of characters escaped in reStructuredText role bodies to avoid unintended markup interpretation." ], "doc_lines_kind": "constant" }, "sphinxcontrib.waterloo_docstrings.extension.WTRL_TOKEN_REPLACEMENTS": { "doc": {}, "doc_lines": [ "A |type|`Mapping` of Waterloo token strings to their corresponding reStructuredText role expansions.", "This mapping is used to convert tokens like |lit|`Must` into the appropriate role." ], "doc_lines_kind": "constant" }, "sphinxcontrib.waterloo_docstrings.extension": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/extension.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract", "Public_classes", "Public_functions", "Public_types", "Public_constants" ] }, "Description": [ "This module provides the Sphinx integration layer for the Waterloo documentation system.", "|", "The implementation operates directly on Docutils nodes and defines custom Docutils roles", "to generate structured documentation output from Waterloo-style docstrings.", "|", "Sphinx is used as the execution and rendering framework, but the internal data model is based", "on the Docutils abstract syntax tree (AST). All document structure, including sections,", "tables, lists, rubrics, and inline markup, is represented using Docutils node classes.", "|", "The module introduces a configurable |type|`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", "|file|`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 |type|`paragraph`, |type|`section`, or |type|`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 |type|`context` which provides abstract roles to be configured by the target project's |file|`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 or method 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 |func|`push`-, |func|`pop`-, |func|`get`-methods.", "MUST maintain a stack with semantics \"current class\" and |func|`push`-, |func|`pop`-, |func|`get`-methods.", "MUST maintain a stack with semantics \"current scope\" and |func|`push`-, |func|`pop`-, |func|`get`-methods.", "MUST provide Docutils directives for modifying these stacks." ] }, "Public_classes": [ "context", "RolePara" ], "Class_overview": { "context": [ "A class that encapsulates Sphinx and Docutils state, configuration, and rendering logic for Waterloo docstring processing." ], "RolePara": [ "Aggregate type for the parameters of role handler functions. |type|`RolePara` is a tuple of the form (role_name, rawtext, text, lineno, inliner, options, content)." ] }, "Public_functions": [ "build_sphinx_nodes", "build_sphinx_nodes_full", "resolve_qualified_name", "wtrl_build_autodoc_module_nodes", "wtrl_build_autodoc_function_nodes", "wtrl_build_autodoc_class_nodes", "wtrl_build_autodoc_class_full_nodes", "wtrl_build_push_current_module_nodes", "wtrl_build_push_current_class_nodes", "wtrl_build_push_current_scope_nodes", "wtrl_build_pop_current_module_nodes", "wtrl_build_pop_current_class_nodes", "wtrl_build_pop_current_scope_nodes", "wtrl_build_method_signature_nodes", "wtrl_build_function_signature_nodes", "wtrl_build_method_signature_block_nodes", "wtrl_build_function_signature_block_nodes", "wtrl_attr_role", "wtrl_class_role", "wtrl_cmd_role", "wtrl_dfn_role", "wtrl_file_role", "wtrl_func_role", "wtrl_label_role", "wtrl_lit_role", "wtrl_mod_role", "wtrl_norm_role", "wtrl_op_role", "wtrl_opt_role", "wtrl_tag_role", "wtrl_type_role", "wtrl_value_role", "wtrl_var_role", "wtrl_var_type_role" ], "Function_overview": { "build_sphinx_nodes": [ "Build a list of Docutils nodes from a docstring tree." ], "build_sphinx_nodes_full": [ "Build a list of Docutils nodes of a class object and its member functions from a docstring tree." ], "resolve_qualified_name": [ "Analyze a qualified name and return the object it refers to plus resolved name components." ], "wtrl_build_autodoc_module_nodes": [ "Implementation of directive |attr|`.. wtrl_autodoc_module::`" ], "wtrl_build_autodoc_function_nodes": [ "Implementation of directive |attr|`.. wtrl_autodoc_function::`" ], "wtrl_build_autodoc_class_nodes": [ "Implementation of directive |attr|`.. wtrl_autodoc_class::`" ], "wtrl_build_autodoc_class_full_nodes": [ "Implementation of directive |attr|`.. wtrl_autodoc_class_full::`" ], "wtrl_build_push_current_module_nodes": [ "Implementation of directive |attr|`.. wtrl_push_current_module::`" ], "wtrl_build_push_current_class_nodes": [ "Implementation of directive |attr|`.. wtrl_push_current_class::`" ], "wtrl_build_push_current_scope_nodes": [ "Implementation of directive |attr|`.. wtrl_push_current_scope::`" ], "wtrl_build_pop_current_module_nodes": [ "Implementation of directive |attr|`.. wtrl_pop_current_module::`" ], "wtrl_build_pop_current_class_nodes": [ "Implementation of directive |attr|`.. wtrl_pop_current_class::`" ], "wtrl_build_pop_current_scope_nodes": [ "Implementation of directive |attr|`.. wtrl_pop_current_scope::`" ], "wtrl_build_method_signature_nodes": [ "Implementation of directive |attr|`.. wtrl_method_signature::`", "Render a method signature with optional class context and inline markup.", "Rendering in a single line can be inconvenient for long signatures; consider using |func|`wtrl_build_method_signature_block_nodes`." ], "wtrl_build_function_signature_nodes": [ "Implementation of directive |attr|`.. wtrl_function_signature::`", "Render a function signature with inline markup.", "Rendering in a single line can be inconvenient for long signatures; consider using |func|`wtrl_build_function_signature_block_nodes`." ], "wtrl_build_method_signature_block_nodes": [ "Implementation of directive |attr|`.. wtrl_method_signature_block::`", "Render a method signature with optional class context and inline markup in a block layout." ], "wtrl_build_function_signature_block_nodes": [ "Implementation of directive |attr|`.. wtrl_function_signature_block::`", "Render a function signature with inline markup in a block layout." ], "wtrl_attr_role": [ "Implementation of role |attr|`:wtrl_attr:`" ], "wtrl_class_role": [ "Implementation of role |attr|`:wtrl_class:`" ], "wtrl_cmd_role": [ "Implementation of role |attr|`:wtrl_cmd:`" ], "wtrl_dfn_role": [ "Implementation of role |attr|`:wtrl_dfn:`" ], "wtrl_file_role": [ "Implementation of role |attr|`:wtrl_file:`" ], "wtrl_func_role": [ "Implementation of role |attr|`:wtrl_func:`" ], "wtrl_label_role": [ "Implementation of role |attr|`:wtrl_label:`" ], "wtrl_lit_role": [ "Implementation of role |attr|`:wtrl_lit:`" ], "wtrl_mod_role": [ "Implementation of role |attr|`:wtrl_mod:`" ], "wtrl_norm_role": [ "Implementation of role |attr|`:wtrl_norm:`" ], "wtrl_op_role": [ "Implementation of role |attr|`:wtrl_op:`" ], "wtrl_opt_role": [ "Implementation of role |attr|`:wtrl_opt:`" ], "wtrl_tag_role": [ "Implementation of role |attr|`:wtrl_tag:`" ], "wtrl_type_role": [ "Implementation of role |attr|`:wtrl_type:`" ], "wtrl_value_role": [ "Implementation of role |attr|`:wtrl_value:`" ], "wtrl_var_role": [ "Implementation of role |attr|`:wtrl_var:`" ], "wtrl_var_type_role": [ "Implementation of role |attr|`:wtrl_var_type:`" ] }, "Public_types": { "ObjectOriginDisplayMode_t": [ "Literal type for configuration variable |var|`wtrl_object_origin_display_mode`." ], "RoleResult": [ "Aggregate type for the return value of role handler functions. |type|`RoleResult` is a tuple of the form (nodes, messages) where nodes is a list of Docutils nodes and messages is a list of Docutils system messages." ] }, "Public_constants": { "RST_TEXT_ESCAPE_CHARS": [ "A |type|`frozenset` of characters escaped in reStructuredText text segments to avoid unintended markup interpretation." ], "RST_ROLE_BODY_ESCAPE_CHARS": [ "A |type|`frozenset` of characters escaped in reStructuredText role bodies to avoid unintended markup interpretation." ], "WTRL_TOKEN_REPLACEMENTS": [ "A |type|`Mapping` of Waterloo token strings to their corresponding reStructuredText role expansions.", "This mapping is used to convert tokens like |lit|`Must` into the appropriate role." ] }, "Notes": { "Last reviewed": [ "2026-07-26" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_context.context": { "signature": { "text": "context.__init__(self, parse_inline: 'Callable[[nodes.Element, int, str], List[nodes.Node]]', lineno: 'int') -> 'None'", "parameters": [ { "name": "parse_inline", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Callable[[nodes.Element, int, str], List[nodes.Node]]", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null } ], "returns": "None" }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Factory", "Public_methods" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide the shared rendering state used by Waterloo Sphinx node builders.", "MUST store the Docutils/Sphinx inline parser callback used to turn resolved Waterloo markup into nodes.", "MUST store the source line number used for diagnostics and inline parsing.", "MUST provide slots for the active Sphinx environment and configuration object.", "MUST provide a cache for validated Waterloo docstrings used by scope-aware link rendering.", "MUST provide a tracer for diagnostics emitted while resolving or rendering Waterloo content.", "MUST provide configurable prolog hook callables for method overview and method block rendering.", "MUST provide access to Waterloo role helper functions through |class|`context_roles`.", "MUST provide a method for applying hook configuration from a simple dictionary." ], "constructor": [ "MUST accept a callable for parsing inline text into a list of |class|`nodes.Node` objects.", "MUST accept a line number for error reporting.", "MUST initialize |attr|`env` and |attr|`config` as unset placeholders.", "MUST initialize default prolog hook callables.", "MUST initialize an empty validated-docstring cache and a fresh tracer." ] }, "Factory": { "make_context": [ "MUST create a |class|`context` instance from a Sphinx application object, an inline parser callable, and a line number." ] }, "Public_methods": [ "__init__" ], "Notes": { "Context population": [ "Call |func|`make_context` instead of instantiating this class directly when Sphinx environment and configuration access are needed." ], "Last reviewed": [ "2026-07-23" ], "Todo": [ "Methods like |func|`build_prolog_method_overview` and |func|`build_prolog_method_block` need to be reviewed." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_context": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_context.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide the |class|`context` class and its factory function |func|`make_context`." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_context.context.__init__": { "signature": { "text": "context.__init__(self, parse_inline: 'Callable[[nodes.Element, int, str], List[nodes.Node]]', lineno: 'int') -> 'None'", "parameters": [ { "name": "parse_inline", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Callable[[nodes.Element, int, str], List[nodes.Node]]", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null } ], "returns": "None" }, "doc": { "Preamble": { "profile": "method", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST initialize the context with the given inline parser and line number.", "MUST initialize the Sphinx environment |var|`env` and configuration |var|`config` placeholders as unset.", "MUST initialize the validated-docstring cache |var|`wtrl_validated_doc_cache` and tracer |var|`tr`." ] }, "Parameters": { "parse_inline": [ "A callable that takes a |class|`nodes.Element` parent, an integer line number, and a string of inline text, and returns a list of |class|`nodes.Node` objects." ], "lineno": [ "An integer line number within the source file." ] }, "Returns": [ "|None|" ], "Raises": {} } }, "sphinxcontrib.waterloo_docstrings.wtrl_context.make_context": { "signature": { "text": "make_context(app: 'SphinxAppProtocol | Any', parse_inline: 'Callable[[nodes.Element, int, str], List[nodes.Node]]', lineno: 'int') -> 'context'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol | Any", "default": null }, { "name": "parse_inline", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Callable[[nodes.Element, int, str], List[nodes.Node]]", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null } ], "returns": "context" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a |class|`context` instance from a Sphinx application object, an inline parser callable, and a line number.", "MUST extract the Sphinx environment and configuration from the application object and store them in the context.", "MUST look for a |var|`docitem_context_configurator` dictionary in the application object or the Sphinx environment.", "MUST apply the configurator to the context if it is found." ] }, "Parameters": { "app": [ "A Sphinx application object." ], "parse_inline": [ "A callable that takes a |class|`nodes.Element` parent, an integer line number, and a string of inline text, and returns a list of |class|`nodes.Node` objects." ], "lineno": [ "An integer line number within the source file." ] }, "Returns": [ "A |class|`context` instance with the Sphinx environment, configuration, and optional configurator applied." ], "Raises": {}, "Notes": { "Last reviewed": [ "2026-07-23" ], "Purpose": [ "This factory function provides a convenient way to create a fully initialized", "rendering context with Sphinx environment and configuration details extracted", "from the application object. It also searches for and applies optional context", "configurators, allowing extensible customization of rendering behavior without", "modifying the context initialization logic directly.", "|", "Called whenever rendering content into the final document (e.g., HTML) at a", "specific source location (|var|`lineno`)." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_state.resolve_qualified_name": { "signature": { "text": "resolve_qualified_name(ctx: 'context | None', qname: 'str') -> 'tuple[object, str, str, list[str]]'", "parameters": [ { "name": "ctx", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "context | None", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "tuple[object, str, str, list[str]]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST resolve the qualified name |var|`qname` using current module/class context in |var|`ctx` when present.", "MUST try to import the resolved object as criterion that resolution succeeded (see section |label|`Raises`)", "MUST try fully qualified forms in this order: current module + current class + |var|`qname`, current module + |var|`qname`, then |var|`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 |type|`(obj, module_name, head_name, tail_parts)` where", "|var|`obj` is the resolved object, |var|`module_name` is the imported module name,", "|var|`head_name` is the last attribute component, and |var|`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." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_state": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_state.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide a set of functions to manage the current module, class, and scope context for Waterloo docstring rendering within Sphinx." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_module_nodes": { "signature": { "text": "wtrl_build_push_current_module_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST push the qualified module name in |var|`text` to the module stack, which makes it the new current module.", "MUST resolve |var|`qname`.", "MUST build a list of Docutils nodes which represent a message about the changed state in the document." ] }, "Description": [ "Implementation of directive |attr|`.. wtrl_push_current_module::`.", "The stack is created dynamically in the Sphinx environment |var|`env`." ], "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 |type|`docutils.nodes.Node` describing the resulting default module state." ], "Raises": { "RuntimeError": [ "MUST raise if |var|`qname` does not resolve to a module." ], "BaseException": [ "MAY propagate exceptions from |func|`resolve_qualified_name`.", "MAY propagate exceptions from within Sphinx or Docutils." ] }, "See_also": [ "wtrl_build_pop_current_module_nodes", "wtrl_build_push_current_class_nodes", "wtrl_build_push_current_scope_nodes" ], "Notes": { "Last reviewed": [ "2026-07-16" ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_be9a1ab921106dd5f883749363ea814d77160c46ab3ec2dc3b19114d088f3f2b" ] }, "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_class_nodes": { "signature": { "text": "wtrl_build_push_current_class_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST push the qualified class name in |var|`text` to the class stack, which makes it the new current class.", "MUST resolve |var|`qname`.", "MUST build a list of Docutils nodes which represent a message about the changed state in the document." ] }, "Description": [ "Implementation of directive |attr|`.. wtrl_push_current_class::`.", "The stack is created dynamically in the Sphinx environment |var|`env`." ], "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 |type|`docutils.nodes.Node` describing the resulting default module state." ], "Raises": { "RuntimeError": [ "MUST raise if |var|`qname` does not resolve to a class." ], "BaseException": [ "MAY propagate exceptions from |func|`resolve_qualified_name`.", "MAY propagate exceptions from within Sphinx or Docutils." ] }, "See_also": [ "wtrl_build_pop_current_class_nodes", "wtrl_build_push_current_module_nodes", "wtrl_build_push_current_scope_nodes" ], "Notes": { "Last reviewed": [ "2026-07-16" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_scope_nodes": { "signature": { "text": "wtrl_build_push_current_scope_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', scope_tag: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "scope_tag", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST push the scope identifier in |var|`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." ] }, "Description": [ "Implementation of directive |attr|`.. wtrl_push_current_scope::`.", "The stack is created dynamically in the Sphinx environment |var|`env`." ], "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 |type|`docutils.nodes.Node` describing the resulting default scope state." ], "Raises": { "RuntimeError": [ "MUST raise if |var|`scope_tag` is unknown." ], "BaseException": [ "MAY propagate exceptions from within Sphinx or Docutils." ] }, "See_also": [ "wtrl_build_pop_current_scope_nodes", "wtrl_build_push_current_module_nodes", "wtrl_build_push_current_class_nodes" ], "Notes": { "Last reviewed": [ "2026-07-16" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_module_nodes": { "signature": { "text": "wtrl_build_pop_current_module_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST compare the qualified module name in |var|`qname` to the top of the module stack and raise an exception in case of mismatch.", "MUST resolve |var|`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." ] }, "Description": [ "Implementation of directive |attr|`.. 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 |type|`docutils.nodes.Node` describing the resulting default module state." ], "Raises": { "RuntimeError": [ "MUST raise on the attempt to access an element from an empty stack.", "MUST raise if the qualified name on top of the stack does not match |var|`qname`.", "MUST raise if |var|`qname` does not resolve to a module." ], "BaseException": [ "MAY propagate exceptions from |func|`resolve_qualified_name`.", "MAY propagate exceptions from within Sphinx or Docutils." ] }, "See_also": [ "wtrl_build_push_current_module_nodes", "wtrl_build_pop_current_class_nodes", "wtrl_build_pop_current_scope_nodes" ], "Notes": { "Last reviewed": [ "2026-07-16" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_class_nodes": { "signature": { "text": "wtrl_build_pop_current_class_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST compare the qualified class name in |var|`qname` to the top of the class stack and raise an exception in case of mismatch.", "MUST resolve |var|`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." ] }, "Description": [ "Implementation of directive |attr|`.. 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 |type|`docutils.nodes.Node` describing the resulting default class state." ], "Raises": { "RuntimeError": [ "MUST raise on the attempt to access an element from an empty stack.", "MUST raise if the qualified name on top of the stack does not match |var|`qname`.", "MUST raise if |var|`qname` does not resolve to a class." ], "BaseException": [ "MAY propagate exceptions from |func|`resolve_qualified_name`.", "MAY propagate exceptions from within Sphinx or Docutils." ] }, "See_also": [ "wtrl_build_push_current_class_nodes", "wtrl_build_pop_current_module_nodes", "wtrl_build_pop_current_scope_nodes" ], "Notes": { "Last reviewed": [ "2026-07-16" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_pop_current_scope_nodes": { "signature": { "text": "wtrl_build_pop_current_scope_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', scope_tag: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "scope_tag", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST compare the scope identifier name in |var|`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." ] }, "Description": [ "Implementation of directive |attr|`.. 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 |type|`docutils.nodes.Node` describing the resulting default scope state." ], "Raises": { "RuntimeError": [ "MUST raise on the attempt to access an element from an empty stack.", "MUST raise if the scope identifier on top of the stack does not match |var|`scope_tag`.", "MUST raise if |var|`scope_tag` is unknown or mismatches the stack top." ], "BaseException": [ "MAY propagate exceptions from within Sphinx or Docutils." ] }, "Notes": { "Last reviewed": [ "2026-07-16" ] }, "See_also": [ "wtrl_build_push_current_scope_nodes", "wtrl_build_pop_current_module_nodes", "wtrl_build_pop_current_class_nodes" ] } }, "sphinxcontrib.waterloo_docstrings.wtrl_state.is_target_obj_visible_in_current_scope": { "signature": { "text": "is_target_obj_visible_in_current_scope(ctx: 'context', obj: 'object') -> 'bool'", "parameters": [ { "name": "ctx", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "context", "default": null }, { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "bool" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST determine whether the target object |var|`obj` is visible in the current Sphinx rendering scope.", "MUST use the current Sphinx environment in |var|`ctx.env` to determine the current Waterloo scope.", "MUST use the Waterloo visibility API to determine whether the target object |var|`obj` is visible in the current Sphinx rendering scope.", "MUST return |True| if the target object |var|`obj` has no docstring, since it m-ay still be in scope but unlinked." ] }, "Parameters": { "ctx": [ "The Waterloo rendering context which provides the current Sphinx environment and configuration." ], "obj": [ "The target object whose visibility in the current Sphinx rendering scope is to be determined." ] }, "Returns": [ "|True| if the target object |var|`obj` is visible in the current Sphinx rendering scope and |False| otherwise." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |func|`_get_validated_doc_for_object`.", "MAY propagate exceptions from |func|`get_current_scope_set`." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_directives.WtrlDirectiveBase": { "signature": { "text": "Directive.__init__(self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine) -> 'None'", "parameters": [ { "name": "name", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "arguments", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "options", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "content", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "content_offset", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "block_text", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "state", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null }, { "name": "state_machine", "kind": "POSITIONAL_OR_KEYWORD", "annotation": null, "default": null } ], "returns": "None" }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Description" ], "scope": [ "extension" ] }, "Description": [ "This is the base class for all Waterloo Sphinx directives. It provides a common implementation of the |func|`run` method. The |func|`run` method calls the directive-specific node builder function, which is passed as an argument to the |func|`_run` method. Derived_classes MUST implement the |func|`run` method, which is called by Sphinx at runtime when the directive is used in a reStructuredText document." ], "Contract": { "general": [ "MUST provide a base class for classes representing Waterloo directives." ], "constructor": [ "SHOULD NOT be instantiated directly. Subclasses are instantiated by Sphinx at runtime when compiling a reStructuredText document." ] }, "Notes": { "Configuration": [ "The directive base class is configured with the following class variables,", "which are evaluated by Sphinx at runtime when the directive is used in a reStructuredText document:", "* |var|`required_arguments`: The number of required arguments for the directive, here: |value|`1`.", "* |var|`has_content`: Indicates whether the directive has content, here: |value|`False`." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_b83b4c46f2627603b955783cfb6738eb8760c900e9c529f295c01371f88a40b0" ] }, "sphinxcontrib.waterloo_docstrings.wtrl_directives": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_directives.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide the Waterloo Sphinx directive classes and the |func|`setup_directives` function to be called by the extension |func|`setup` function." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_markup.resolve_markup": { "signature": { "text": "resolve_markup(text: 'str', ctx: 'context') -> 'str'", "parameters": [ { "name": "text", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "ctx", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "context", "default": null } ], "returns": "str" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST convert Waterloo inline markup syntax into reStructuredText role directives.", "MUST process both naked tokens and |role|`body` markup patterns.", "MUST escape special RST characters in text segments while preserving markup boundaries.", "MUST return the converted markup string ready for Sphinx processing." ] }, "Parameters": { "text": [ "The source text containing Waterloo markup patterns to resolve.", "Markup patterns include naked tokens (MUST, MAY, |True|, |False|, etc.)", "and structured marks (|tag|`body`, e.g., |type|`str`, |attr|`enabled`)." ], "ctx": [ "The |type|`context` object providing scope information for markup resolution,", "used by helper functions to resolve qualified names and check visibility.", "For currently simple roles this parameter is mostly structural, but reference", "markup and future context-aware transformations require access to the active", "Sphinx/Waterloo rendering state." ] }, "Returns": [ "The input text with all recognized Waterloo markup patterns converted to Sphinx role syntax.", "Text segments outside markup are escaped for RST special characters.", "The returned string is ready for parsing by the Sphinx RST parser." ], "Raises": { "Exception": [ "MAY propagate if context operations fail during markup resolution (e.g., qualified name resolution in nested contexts)." ] }, "See_also": [ "RST_TEXT_ESCAPE_CHARS", "RST_ROLE_BODY_ESCAPE_CHARS", "WTRL_TOKEN_REPLACEMENTS" ], "Notes": { "Markup_conversion": [ "* Naked tokens like '|' + Must + '|' \u2192 :wtrl_norm:`Must`", "* Structured markup like '|' + role + '|' + `body` \u2192 :wtrl_role:`body`." ], "Escaping": [ "Text segments outside markup use |var|`RST_TEXT_ESCAPE_CHARS` (backslash, backtick, asterisk, underscore, pipe, angles).", "Role bodies use |var|`RST_ROLE_BODY_ESCAPE_CHARS` (backslash, backtick only)." ], "Context": [ "The context parameter keeps this function aligned with the node-building pipeline.", "Most replacements are textual today, but |ref| markup, forward references, scope-sensitive rendering, and future role-specific normalization depend on contextual state." ], "Performance": [ "Uses compiled regex patterns for efficient token and markup boundary detection." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_markup": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_markup.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide helpers for Waterloo roles in Sphinx." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_parse.parse_inline": { "signature": { "text": "parse_inline(inliner: 'InlinerProtocol', parent: 'nodes.Element', ln: 'int', txt: 'str') -> 'List[nodes.Node]'", "parameters": [ { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "parent", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "nodes.Element", "default": null }, { "name": "ln", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "txt", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "List[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST parse inline reStructuredText content and preserve warning and error messages.", "MUST append all generated messages to the parent element as child nodes.", "MUST return all parsed content nodes without discarding messages." ] }, "Description": [ "This function wraps inliner.parse() to ensure that any warning or error messages", "generated during the parsing process are captured and added to the document tree", "instead of being silently discarded." ], "Parameters": { "inliner": [ "An inline element parser implementing InlinerProtocol. MUST have a parse method", "and a document attribute with settings and reporter attributes." ], "parent": [ "The parent Element to which parsed content and messages will be appended." ], "ln": [ "The line number (integer) where the txt input begins in the source document." ], "txt": [ "The reStructuredText source string (str) to be parsed for inline markup." ] }, "Returns": [ "List of parsed docutils.nodes.Node instances representing the content found in txt.", "The returned list is created from the parse output; warning and error messages are", "appended directly to parent and not returned as part of the list." ], "Raises": { "BaseException": [ "Exceptions from underlying RST parsing or document handling MAY propagate depending on the inliner implementation." ] }, "Notes": { "Key difference from direct inliner.parse() calls": [ "This function always preserves document messages in the tree. Direct calls to", "inliner.parse() may discard messages, leading to silent data loss in warnings", "and error conditions." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_parse": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_parse.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide a function for inline parsing using a Sphinx Inliner object." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_roles.RolePara": { "signature": { "text": "RolePara.__init__(self, name: 'str', rawtext: 'str', text: 'str', lineno: 'int', inliner: 'InlinerProtocol', options: 'Mapping[str, Any] | None', content: 'list[str] | None') -> None", "parameters": [ { "name": "name", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "rawtext", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "text", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "options", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Mapping[str, Any] | None", "default": null }, { "name": "content", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "list[str] | None", "default": null } ], "returns": "None" }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST be a frozen dataclass that aggregates the parameters passed to Docutils role handler functions." ], "constructor": [ "Default" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_roles": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_roles.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide functions for registering the Waterloo roles with Docutils/Sphinx." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_attr_role": { "signature": { "text": "wtrl_attr_role(para: 'RolePara') -> 'RoleResult'", "parameters": [ { "name": "para", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RolePara", "default": null } ], "returns": "RoleResult" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a |type|`docutils.nodes.literal` node with the text in |var|`para.text` and the CSS class |value|`wtrl_attr`.", "MUST return the created node as the only generated document node.", "MUST return an empty list of system messages." ] }, "Parameters": { "para": [ "|class|`RolePara` instance containing the normalized Docutils role parameters." ] }, "Returns": [ "A |type|`RoleResult` containing a one-element node list and an empty system-message list." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |type|`docutils`." ] }, "See_also": [ "RolePara", "RoleResult" ], "Notes": { "Representative role": [ "This docstring documents the common implementation pattern used by the simple Waterloo roles in this module.", "Most of these roles create either one |type|`docutils.nodes.literal` node or one |type|`docutils.nodes.inline` node, attach a semantic CSS class, and return no system messages." ], "Node kind": [ "Object-like roles such as |lit|`wtrl_attr`, |lit|`wtrl_func`, and |lit|`wtrl_type` use literal nodes.", "Text-semantic roles such as |lit|`wtrl_dfn`, |lit|`wtrl_label`, |lit|`wtrl_norm`, and |lit|`wtrl_term` use inline nodes." ], "Examples": [ "* |attr|`my_attribute`", "* JSON-like text: { \"|attr|`my_attribute`\": \"|value|`my_value`\" }" ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_roles.wtrl_var_type_role": { "signature": { "text": "wtrl_var_type_role(para: 'RolePara') -> 'RoleResult'", "parameters": [ { "name": "para", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RolePara", "default": null } ], "returns": "RoleResult" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST parse the text in |var|`para.text` as a variable name and type separated by the first colon.", "MUST strip surrounding whitespace from the parsed variable name and type.", "MUST return a Docutils error system message if |var|`para.text` does not contain a colon.", "MUST return a Docutils error system message if either the parsed variable name or type is empty.", "MUST create a wrapper |type|`docutils.nodes.inline` node with CSS class |value|`wtrl_var_type` for valid input.", "MUST add the variable name as a child inline node with CSS class |value|`wtrl_var`.", "MUST add a colon as a child inline node with CSS class |value|`wtrl_op`.", "MUST add the type as a child inline node with CSS class |value|`wtrl_type`." ] }, "Parameters": { "para": [ "|class|`RolePara` instance containing the normalized Docutils role parameters." ] }, "Returns": [ "On valid input, a |type|`RoleResult` containing one wrapper node and an empty system-message list.", "On invalid input, a |type|`RoleResult` containing no document nodes and one Docutils error system message." ], "Raises": { "BaseException": [ "MAY propagate unexpected exceptions from |type|`docutils`." ] }, "See_also": [ "RolePara", "RoleResult" ], "Notes": { "Structure": [ "This role is intentionally different from the simple Waterloo roles because it exposes the variable name, separator, and type as separately styleable inline nodes." ], "Separator": [ "Only the first colon separates variable and type. Additional colons remain part of the type text." ], "Examples": [ "* |var_type|`n: int`", "* |var_type|`q: float`", "* |var_type|`para: RolePara`", "* |var_type|`result: tuple[List[nodes.Node], list[nodes.Node]]`" ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_nodes": { "signature": { "text": "wtrl_build_method_signature_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a list of |type|`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 |type|`docutils.nodes.Node` describing the method signature." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |type|`docutils`." ] }, "See_also": [ "wtrl_build_function_signature_nodes", "wtrl_build_method_signature_block_nodes" ], "Notes": { "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_signature": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_signature.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide functions to render method and function signatures as Docutils nodes, both in inline and block formats." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_nodes": { "signature": { "text": "wtrl_build_function_signature_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a list of |type|`docutil`-nodes representing the function signature as inline text." ] }, "Parameters": { "app": [ "The Sphinx application instance that carries configuration and environment state." ], "inliner": [ "The Docutils inliner used to parse inline markup into nodes." ], "lineno": [ "Line number in the source document." ], "qname": [ "Qualified name of function to render." ] }, "Returns": [ "The list of generated |type|`docutils.nodes.Node` describing the function signature." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |type|`docutils`." ] }, "See_also": [ "wtrl_build_method_signature_nodes", "wtrl_build_function_signature_block_nodes" ], "Notes": { "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_method_signature_block_nodes": { "signature": { "text": "wtrl_build_method_signature_block_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a list of |type|`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 |type|`docutils.nodes.Node` describing the method signature." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |type|`docutils`." ] }, "See_also": [ "wtrl_build_method_signature_nodes", "wtrl_build_function_signature_block_nodes" ], "Notes": { "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_signature.wtrl_build_function_signature_block_nodes": { "signature": { "text": "wtrl_build_function_signature_block_nodes(app: 'SphinxAppProtocol', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a list of |type|`docutil`-nodes representing the function signature as paragraph with one parameter per line." ] }, "Parameters": { "app": [ "The Sphinx application instance that carries configuration and environment state." ], "inliner": [ "The Docutils inliner used to parse inline markup into nodes." ], "lineno": [ "Line number in the source document." ], "qname": [ "Qualified name of function to render." ] }, "Returns": [ "The list of generated |type|`docutils.nodes.Node` describing the function signature." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |type|`docutils`." ] }, "See_also": [ "wtrl_build_method_signature_block_nodes", "wtrl_build_function_signature_nodes" ], "Notes": { "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes": { "signature": { "text": "build_sphinx_nodes(ctx: 'context', obj: 'object', doc: 'mod_docitem.docitem_docstring_base') -> 'List[nodes.Node]'", "parameters": [ { "name": "ctx", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "context", "default": null }, { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null }, { "name": "doc", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "mod_docitem.docitem_docstring_base", "default": null } ], "returns": "List[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST convert a parsed Waterloo docstring into docutils nodes for Sphinx output.", "MUST honor the current Waterloo scope before rendering the documented object.", "MUST return an empty node list if the documented object is outside the current scope and scope-filter placeholders are disabled.", "MUST render a note-style placeholder if the documented object is outside the current scope and scope-filter placeholders are enabled.", "MUST assign a deterministic anchor id to the documentation box.", "MUST register the anchor id for cross-document Waterloo references.", "MUST render the docstring as a two-column documentation box with section labels on the left and rendered section content on the right.", "MUST add a signature row for callable objects.", "MUST preserve section-specific structure, for example executable-contract bullet lists, free-form paragraphs, grouped definitions, and public-object lists.", "MUST resolve selected reference-like entries as internal links where targets can be resolved.", "MUST mark resolvable but scope-filtered reference targets as out-of-scope entries.", "MUST keep unresolved reference entries visible as role-rendered fallback text.", "MUST emit runtime warnings for unresolved entries in sections where linkability is expected.", "MUST NOT raise hard validation errors for unresolved references; semantic enforcement belongs to the validator." ] }, "Parameters": { "ctx": [ "Rendering context providing Sphinx state, configuration, inline parsing, and Waterloo role helpers." ], "obj": [ "The documented Python object." ], "doc": [ "Parsed Waterloo docstring tree for |var|`obj`." ] }, "Returns": [ "List of |type|`docutils.nodes.Node` representing the rendered documentation box or scope-filter placeholder." ], "Raises": { "NotImplementedError": [ "MAY raise if the docstring contains a section shape that is not supported by this renderer." ], "RuntimeError": [ "MAY raise if unexpected section structure is encountered." ], "ValueError": [ "MAY raise if free-form itemization starts with an invalid nested list structure." ], "RuntimeWarning": [ "MAY emit warnings for unresolved link targets (for example in |label|`Public_*`, |label|`Derived_from`, or normative |label|`See_also`)." ] }, "Notes": { "Usage": [ "This function is typically not called directly. It is called", "by the various |func|`autodoc` functions." ], "Scope filtering": [ "Scope filtering is handled before the documentation box is built.", "When placeholders are enabled, skipped objects remain visible in the rendered document as lightweight notes." ], "Linking": [ "Internal links are created using anchor ids from |func|`build_anchor` and the Sphinx environment's Waterloo anchor index.", "Built-in exceptions in section |label|`Raises` are intentionally rendered as plain text without internal links." ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_autodoc": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_autodoc.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide functions for rendering Waterloo docstrings in Sphinx." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes_full": { "signature": { "text": "build_sphinx_nodes_full(ctx: 'context', class_obj: 'Any', session: 'mod_docitem.DocSession') -> 'List[nodes.Node]'", "parameters": [ { "name": "ctx", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "context", "default": null }, { "name": "class_obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Any", "default": null }, { "name": "session", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "mod_docitem.DocSession", "default": null } ], "returns": "List[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST parse and validate the Waterloo docstring of |var|`class_obj`.", "MUST validate the class method coverage declared by the class docstring.", "MUST return an empty node list if the class docstring is outside the current Waterloo scope.", "MUST render the class docstring with |func|`build_sphinx_nodes`.", "MUST recursively render nested classes listed in |label|`Public_classes` if they exist on |var|`class_obj`.", "MUST render public methods listed in |label|`Public_methods` if they exist, resolve to function objects, have docstrings, validate successfully, and are visible in the current Waterloo scope.", "MUST insert method block prolog nodes before rendered public methods.", "MUST render documented property accessor methods for property entries listed in |label|`Public_variables`.", "MUST reuse |var|`session` for parsing and validation work performed during the recursive render pass.", "MAY skip listed members that cannot be found, cannot be represented as function objects, or do not have docstrings." ] }, "Parameters": { "ctx": [ "Rendering context providing Sphinx state, configuration, diagnostics, inline parsing, and Waterloo role helpers." ], "class_obj": [ "The class object to render." ], "session": [ "Session object used for parser and validator state shared across the recursive render pass." ] }, "Returns": [ "List of |type|`docutils.nodes.Node` representing the class, nested classes, public methods, and documented property accessors." ], "Raises": { "RuntimeError": [ "MUST raise if |var|`class_obj` has no docstring.", "MAY raise if parsing or validation of the class docstring fails.", "MAY raise if rendering the class docstring fails." ], "NotImplementedError": [ "MAY forward unsupported section-shape errors from |func|`build_sphinx_nodes`." ], "ValueError": [ "MAY forward free-form itemization errors from |func|`build_sphinx_nodes`." ], "BaseException": [ "MAY forward exceptions from Sphinx or the Waterloo parser/validator." ] }, "Notes": { "Member errors": [ "The current method-rendering branch is intentionally tolerant and may skip problematic methods instead of aborting the complete class rendering pass." ], "Scope filtering": [ "Unlike |func|`build_sphinx_nodes`, this helper currently omits an out-of-scope class without rendering a placeholder." ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_module_nodes": { "signature": { "text": "wtrl_build_autodoc_module_nodes(app: 'SphinxAppProtocol | Any', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol | Any", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a Waterloo rendering context for the active Sphinx application and source line.", "MUST resolve the dotted module name |var|`qname` to a Python module object, taking the current Waterloo module state into account.", "MUST return diagnostic nodes if |var|`qname` cannot be resolved.", "MUST return diagnostic nodes if |var|`qname` does not resolve to a module.", "MUST return diagnostic nodes if the resolved module has no non-empty docstring.", "MUST parse and validate the module's Waterloo docstring.", "MUST return structured tracer diagnostic nodes if parsing or validation fails.", "MUST render the parsed docstring with |func|`build_sphinx_nodes`." ] }, "Description": [ "Implementation of directive |attr|`.. wtrl_autodoc_module::`." ], "Parameters": { "app": [ "The Sphinx application instance that carries configuration and environment state." ], "inliner": [ "The Docutils inliner used to parse inline markup into nodes." ], "lineno": [ "Line number in the source document." ], "qname": [ "The qualified module name to build nodes for." ] }, "Returns": [ "List of generated |type|`docutils.nodes.Node` representing the module documentation or a diagnostic replacement." ], "Raises": { "BaseException": [ "MAY forward unexpected exceptions from context creation, inline parsing, or |func|`build_sphinx_nodes`." ] }, "Notes": { "Diagnostics": [ "Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors." ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_nodes": { "signature": { "text": "wtrl_build_autodoc_class_nodes(app: 'SphinxAppProtocol | Any', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol | Any", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a Waterloo rendering context for the active Sphinx application and source line.", "MUST resolve the dotted class name |var|`qname` to a class, taking the current Waterloo module/class state into account.", "MUST return diagnostic nodes if |var|`qname` cannot be resolved.", "MUST return diagnostic nodes if |var|`qname` does not resolve to a class.", "MUST return diagnostic nodes if the resolved class has no non-empty docstring.", "MUST parse and validate the class' Waterloo docstring.", "MUST return structured tracer diagnostic nodes if parsing or validation fails.", "MUST render the parsed docstring with |func|`build_sphinx_nodes`." ] }, "Description": [ "Implementation of directive |attr|`.. 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 |type|`docutils.nodes.Node` representing the class documentation or a diagnostic replacement." ], "Raises": { "BaseException": [ "MAY forward unexpected exceptions from context creation, inline parsing, or |func|`build_sphinx_nodes`." ] }, "Notes": { "Diagnostics": [ "Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors." ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_function_nodes": { "signature": { "text": "wtrl_build_autodoc_function_nodes(app: 'SphinxAppProtocol | Any', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol | Any", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a Waterloo rendering context for the active Sphinx application and source line.", "MUST resolve the dotted function name |var|`qname` to a callable, taking the current Waterloo module/class state into account.", "MUST return diagnostic nodes if |var|`qname` cannot be resolved.", "MUST return diagnostic nodes if |var|`qname` does not resolve to a callable.", "MUST return diagnostic nodes if the resolved callable has no non-empty docstring.", "MUST parse and validate the function's Waterloo docstring.", "MUST return structured tracer diagnostic nodes if parsing or validation fails.", "MUST render |value|`function` and |value|`method` profiles as method docstrings.", "MUST render all other accepted callable profiles as inherited-method docstrings.", "MUST render the parsed docstring with |func|`build_sphinx_nodes`." ] }, "Description": [ "Implementation of directive |attr|`.. 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 |type|`docutils.nodes.Node` representing the callable documentation or a diagnostic replacement." ], "Raises": { "BaseException": [ "MAY forward unexpected exceptions from context creation, inline parsing, or |func|`build_sphinx_nodes`." ] }, "Notes": { "Diagnostics": [ "Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors." ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_autodoc.wtrl_build_autodoc_class_full_nodes": { "signature": { "text": "wtrl_build_autodoc_class_full_nodes(app: 'SphinxAppProtocol | Any', inliner: 'InlinerProtocol', lineno: 'int', qname: 'str') -> 'list[nodes.Node]'", "parameters": [ { "name": "app", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "SphinxAppProtocol | Any", "default": null }, { "name": "inliner", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "InlinerProtocol", "default": null }, { "name": "lineno", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "int", "default": null }, { "name": "qname", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[nodes.Node]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST create a Waterloo rendering context for the active Sphinx application and source line.", "MUST resolve the dotted class name |var|`qname` to a class, taking the current Waterloo module/class state into account.", "MUST return diagnostic nodes if |var|`qname` cannot be resolved.", "MUST return diagnostic nodes if |var|`qname` does not resolve to a class.", "MUST return diagnostic nodes if the resolved class has no non-empty docstring.", "MUST delegate recursive class, nested-class, method, and property-accessor rendering to |func|`build_sphinx_nodes_full`.", "MUST return runtime diagnostic nodes if |func|`build_sphinx_nodes_full` raises |type|`RuntimeError`.", "MUST return structured tracer diagnostic nodes if recursive rendering fails with another expected exception." ] }, "Description": [ "Implementation of directive |attr|`.. 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 |type|`docutils.nodes.Node` representing the recursively rendered class documentation or a diagnostic replacement." ], "Raises": { "BaseException": [ "MAY forward unexpected exceptions from context creation, inline parsing, or diagnostic rendering." ] }, "Notes": { "Diagnostics": [ "Expected directive failures are rendered into the document instead of being raised as hard Sphinx build errors." ], "Recursion": [ "The traversal policy is implemented by |func|`build_sphinx_nodes_full`; this directive wrapper only resolves the top-level class and translates failures into Sphinx nodes." ], "Last reviewed": [ "2026-07-23" ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_protocol.InlinerProtocol": { "signature": { "text": "_no_init_or_replace_init(self, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract" ] }, "Contract": { "general": [ "MUST describe the subset of the Docutils/Sphinx inliner interface used by Waterloo role and directive rendering.", "MUST expose the document and reporter attributes used by helper functions that parse inline markup.", "MUST expose a parse method that converts inline reStructuredText into Docutils nodes.", "MUST be used for structural typing and developer documentation only." ], "constructor": [] }, "Notes": { "Runtime": [ "This protocol is structural and is not instantiated by the extension.", "Sphinx provides the concrete object at runtime." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_protocol": { "path": "/server/devel/sdv/privat/uwe/source/sdv_doc_waterloo/package_sphinx/src/sphinxcontrib/waterloo_docstrings/wtrl_protocol.py", "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST provide protocol definitions for Sphinx Inliner and Sphinx App objects to enable type checking and static analysis." ] }, "Notes": { "Usage": [ "Do not import this module directly. Use the functions via the |ref|`extension ` module instead." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_protocol.SphinxEnvProtocol": { "signature": { "text": "_no_init_or_replace_init(self, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract" ] }, "Contract": { "general": [ "MUST describe the subset of the Sphinx build-environment interface used by this extension.", "MUST expose the current document name used for diagnostics and context-sensitive rendering.", "MUST expose the Waterloo context configurator storage used while rendering directives and roles.", "MUST be used for structural typing and developer documentation only." ], "constructor": [] }, "Notes": { "Runtime": [ "This protocol is structural and is not instantiated by the extension.", "Sphinx provides the concrete object at runtime." ] } } }, "sphinxcontrib.waterloo_docstrings.wtrl_protocol.SphinxAppProtocol": { "signature": { "text": "_no_init_or_replace_init(self, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract" ] }, "Contract": { "general": [ "MUST describe the subset of the Sphinx application interface used by this extension.", "MUST expose the build environment, configuration object, and Waterloo context configurator storage.", "MUST provide the structural shape expected by directive, state, signature, and autodoc helpers.", "MUST be used for structural typing and developer documentation only." ], "constructor": [] }, "Notes": { "Runtime": [ "This protocol is structural and is not instantiated by the extension.", "Sphinx provides the concrete object at runtime." ] } } } }, "__WTRL_EXAMPLES__": { "sha256_b83b4c46f2627603b955783cfb6738eb8760c900e9c529f295c01371f88a40b0": { "lang": "python", "hash": "b83b4c46f2627603b955783cfb6738eb8760c900e9c529f295c01371f88a40b0", "code": "# This is how the class is used in wtrl_directives.py.\n# wtrl_build_autodoc_module_nodes is defined in wtrl_autodoc.py\n\n# Directive class derived from the common base class.\nclass WtrlAutodocModuleDirective(WtrlDirectiveBase):\n\tdef run(self) -> list[nodes.Node]:\n\t\treturn self._run(wtrl_build_autodoc_module_nodes)\n\n# More directive classes here...\n\n# Invoked by the extension's setup-function.\ndef setup_directives(app: SphinxAppProtocol) -> None:\n\tapp.add_directive(\"wtrl_autodoc_module\", WtrlAutodocModuleDirective)\n\t# More directives here...\n", "referenced_by": [ "sphinxcontrib.waterloo_docstrings.wtrl_directives.WtrlDirectiveBase" ] }, "sha256_be9a1ab921106dd5f883749363ea814d77160c46ab3ec2dc3b19114d088f3f2b": { "lang": "python", "hash": "be9a1ab921106dd5f883749363ea814d77160c46ab3ec2dc3b19114d088f3f2b", "code": "\n# Directive class derived from the common base class.\nclass WtrlPushCurrentModuleDirective(WtrlDirectiveBase):\n\tdef run(self) -> list[nodes.Node]:\n\t\treturn self._run(wtrl_build_push_current_module_nodes)\n\n# More directive classes here...\n\n# Invoked by the extension's setup-function.\ndef setup_directives(app: SphinxAppProtocol) -> None:\n\t# other calls to add_directive\n\tapp.add_directive(\"wtrl_push_current_module\", WtrlPushCurrentModuleDirective)\n\t# more calls to add_directive\n", "referenced_by": [ "sphinxcontrib.waterloo_docstrings.wtrl_state.wtrl_build_push_current_module_nodes" ] } } }