5. Roles

5.1. Semantic Markup

The following module demonstrates how to use roles in docstrings. The general Waterloo notation inside docstrings is |role|`par`, that is, the role name in pipe delimiters followed by a string-valued parameter enclosed in backticks.

Preamble	normative sections Contract, Definitions
Definitions	Unicorn A sample definition we need for demonstrating the term token.
Contract	general Must visualize the semantic markup for documentation and testing
Notes	Attribute Rendering: abc, ABC Code: |attr|`abc`, |attr|`ABC` Semantics: keys in JSON, TOML, YAML; attributes in XML Example: “In the rendered artifact __WTRL_VERSION__ contains the version string” Class Rendering: abc, ABC Code: |class|`abc`, |class|`ABC` Semantics: classes in programming languages; maybe tables in database query languages Example: “See docstring of class tracer for details.” Command Rendering: abc, ABC Code: |cmd|`abc`, |cmd|`ABC` Semantics: Command line tools, subcommands of tools Example: “In the terminal invoke waterlint validate --basedir /path/to/input” Definition Rendering: abc, ABC Code: |dfn|`abc`, |dfn|`ABC` Semantics: A term defined in a Definitions or Terminology section. Example: “A Unicorn is a mythical equine of the genus Monocerus…” Note: In the context of Waterloo Docstrings this token mainly appears in the Definitions section, and it has an impact on the |term| token. File Rendering: /path/to/abc, S:\ABC Code: |file|`/path/to/abc`, |file|`S:\\ABC` Semantics: A path in the file system Example: “Add $ROOT_DIR/examples-python to your PATH environment variable.” Function Rendering: print, MyClass.my_method Code: |func|`print`, |class|`|MyClass.my_method|` Semantics: A function name, or function call syntax. Example: “Call update after configuring.” Note: It is a matter of taste how callable class objects should be marked, with obj() or obj(). Caveat: A more concise way for the combination class/method is to wrap the class name separately: MyClass.my_method which is written like |class|`MyClass`|op|`.`|func|`my_method`. Note however that the monochrome method is easier to process for an LLM, since more markup means more “noise”. There seems to be a “sweet spot” for the amount of markup to be applied ideally. Key Rendering: Q, CTRL + Z Code: |key|`Q`, |key|`CTRL` +` |lit|`|key|`Z` Semantics: A key on the keyboard Example: “Press CTRL + SHIFT + P to open the command palette.” Note: Combined keys require white space around the + operator. Label Rendering: abc, ABC Code: |label|`abc`, |label|`ABC` Semantics: A title, headline, section marker, rubric marker Example: “The Preamble | must | be present in each docstring.” Literal Rendering: abc, ABC Code: |lit|`abc`, |lit|`ABC` Semantics: Generally a literal snippet, e.g. for code; a catchall for cases not covered by other semantics rolls. Example: “User waltraud at host fancybox.” Module Rendering: abc, ABC Code: |mod|`abc`, |mod|`ABC` Semantics: A module or a plugin; something that can be imported or included. Example: “Class tracer is defined in module docitem_helper.” Normativity token Rendering: Should, must Code: |norm|`Should`, |norm|`must` Semantics: A role for marking normativity keywords. Example: “Normativity keyword ‘should’ expresses a requirement to be fulfilled under normal conditions.” Note: The range of applications for this role is limited, since it is mainly for speaking about normativity, not for composing a normative statement. Operator Rendering: +, * Code: |op|`+`, |op|`*` Semantics: Any kind of operator in programming or markup languages. Example: “In Python, ‘not’ is an operator.” Notes Rendering: -a, --no-debug Code: |opt|`-a`, |opt|`--no-debug` Semantics: An option for a commandline call Example: “List all files in long format: ls -la” Package Rendering: abc, ABC Code: |pkg|`abc`, |pkg|`ABC` Semantics: A package; something that can be installed. Example: “We recommend to install Sphinx theme furo.” Example: “Import module sdv.doc.waterloo.docitem_helper…” Tag Rendering: <abc>, or <ABC attr = "value"> Code: |tag|`<abc>`, or <|tag|`ABC` |attr|`attr` = |value|`"value"`> Semantics: A tag in XML; maybe the key of a compound object in JSON or a section marker in TOML. Term Rendering: Unicorn Code: |term|`Unicorn` Semantics: Refer to a term defined in the Definitions section. Example: “Following our definition of a Unicorn we can easily conclude that…” Type Rendering: float, BaseException Code: |type|`float`, |type|`BaseException` Semantics: A type. This overlaps with the |class| role. Example: “All parameters | must | have type int or float. URL Rendering: https://github.com Code: |url|`https://github.com` Semantics: A non-clickable URL Example: “The Schema ID is https://sci-d-vis.com/schema/wtrl-json-0.1.0.schema.json.” Note: For clickable URLs, use the |ref| role instead. Value Rendering: 12345, "ABC" Code: |value|`12345`, |value|`"ABC"` Semantics: A non-assignable value; an R-value; a symbolic constant. Example: “Specify date in ISO 8601 format, e.g. 2026-07-17.” Variable Rendering: use_color, PATH Code: |var|`use_color`, |var|`PATH` Semantics: An assignable object; a function parameter; a named value; a constant some value is assigned to. Example: “Parameter text contains the text to be rendered.” Variable and type Rendering: use_color: bool Code: |var_type|`use_color:bool` Semantics: A pair of variable and type in colon notation. Example: “Annotate the parameter list like so: (a: int, b: str,…).”
«Module»	doc_roles

The Waterloo renderer converts these roles into ordinary reST roles. You can also use these roles in running text. Some of them overlap conceptually with the standard Sphinx role set. It is up to the author to choose the roles that best express the intended meaning. For machine readability, the important part is simply that the Waterloo notation is used inside docstrings.

Rendered	Code
abc, ABC	:wtrl_attr:`abc`, :wtrl_attr:`ABC`
abc, ABC	:wtrl_class:`abc`, :wtrl_class:`ABC`
abc, ABC	:wtrl_cmd:`abc`, :wtrl_cmd:`ABC`
abc, ABC	:wtrl_dfn:`abc`, :wtrl_dfn:`ABC`
/path/to/abc, S:\ABC	:wtrl_file:`/path/to/abc`, :wtrl_file:`S:\\ABC`
print, MyClass.my_method	:wtrl_func:`print`, :wtrl_func:`MyClass.my_method`
Q, CTRL + Z	:wtrl_key:`Q`, :wtrl_key:`CTRL` + :wtrl_key:`Z`
abc, ABC	:wtrl_label:`abc`, :wtrl_label:`ABC`
abc, ABC	:wtrl_lit:`abc`, :wtrl_lit:`ABC`
abc, ABC	:wtrl_mod:`abc`, :wtrl_mod:`ABC`
Should, must	:wtrl_norm:`Should`, :wtrl_norm:`must`
+, *	:wtrl_op:`+`, :wtrl_op:`*`
-a, --no-debug	:wtrl_opt:`-a`, :wtrl_opt:`--no-debug`
abc, ABC	:wtrl_pkg:`abc`, :wtrl_pkg:`ABC`
abc, ABC	:wtrl_tag:`abc`, :wtrl_tag:`ABC`
Unicorn	:wtrl_term:`Unicorn`
float, BaseException	:wtrl_type:`float`, :wtrl_type:`BaseException`
https://github.com	:wtrl_url:`https://github.com`
12345, "ABC"	:wtrl_value:`12345`, :wtrl_value:`"ABC"`
use_color, PATH	:wtrl_var:`use_color`, :wtrl_var:`PATH`
use_color: bool	:wtrl_var_type:`use_color:bool`

5.2. Normativity and value tokens

The Waterloo Docstring format offers a fixed set of normativity keywords inspired by RFC 2119. MAY NOT is intentionally omitted because it is semantically ambiguous in this context. The format also defines a small set of values in tokenized form. The following module rendering gives a compact overview of these tokens.

Preamble	normative sections Contract, Description
Contract	general Must demonstrate how normativity tokens and value tokens are rendered.
Description	Section Description is marked as normative, so that normativity tokens can be demonstrated in regular prose. Requirement Rendering: Must, must Code: |Must|, |must| Semantics: Requirement tokens mark mandatory statements. Negative requirement Rendering: Must not, must not Code: |Must_not|, |must_not| Semantics: Negative requirement tokens mark prohibited statements. Recommendation Rendering: Should, should Code: |Should|, |should| Semantics: Recommendation tokens mark statements that should normally be followed. Negative recommendation Rendering: Should not, should not Code: |Should_not|, |should_not| Semantics: Negative recommendation tokens mark statements that should normally be avoided. Option, permission Rendering: May, may Code: |May|, |may| Semantics: Permission tokens mark allowed options.
Notes	Boolean value tokens Rendering: True, False Code: |True|, |False| Semantics: Boolean value tokens mark predefined truth values. Example: “The function returns True if the input is valid, and False otherwise.” None value token Rendering: None Code: |None| Semantics: The None value token marks the absence of a value. Example: “The function returns None if the input is invalid, and a valid result otherwise.” Self value token Rendering: Self Code: |Self| Semantics: The Self value token marks the conventional self-reference value. Example: “The method returns Self for fluent chaining.” Empty value token Rendering: <empty> Code: |empty| Semantics: The <empty> value token marks an explicitly empty value or set. Caveat: Do not use <empty> as a placeholder for unknown or missing content.
«Module»	doc_normativity_and_value_tokens

5.3. Cross referencing

The following classes from the module doc_cross_referencing in ${REPO}/examples-python demonstrate the different forms of cross-references.

• References to other objects within the module

  • By identifier

  • By qualified identifier (module + object)

• References to other objects outside the module

  • By fully qualified identifier (package + module + object)

• References to labels in the surrounding Sphinx document

  • in the same file

  • in a different file

• References to web pages (HTTP / HTTPS)

• References to non-existent targets

Pay attention to how the reference target is written:

• |ref|`Label <wtrl://...>` – use wtrl:// for Waterloo docstring objects.

• |ref|`label <http[s]://...>` – use http:// or https:// for web pages.

• |ref|`Label <...>` – omit the scheme for references within the project.

Waterloo module context

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

Preamble	normative sections Contract
Contract	general Must contain cross references for demonstration purposes. constructor
Notes	Reference to a documented object (same module) Rendering: B Code: \|ref\|\`B <wtrl://B>\` Semantics: Cross reference to a documented object. For testing purposes, we use an unqualified name here, which is resolved to the fully qualified name of the class B in this module. Reference to a documented object (different module) Rendering: build_sphinx_nodes Code: \|ref\|\`build_sphinx_nodes <wtrl://sphinxcontrib.waterloo_docstrings.wtrl_autodoc.build_sphinx_nodes>\` Semantics: Cross reference to a documented object. Note: Forward reference. Reference to a non-existing object Rendering: nonexisting_function Reference to a web page Rendering: Python Code: \|ref\|\`Python <https://www.python.org/>\` Semantics: Cross reference to a web page.
«Class»	A

Preamble	normative sections Contract
Contract	general Must contain cross references for demonstration purposes. constructor
Notes	Reference to a documented object Rendering: A Code: \|ref\|\`A <wtrl://doc_cross_referencing.A>\` Semantics: Cross reference to a documented object. For testing purposes, we use a fully qualified name here, which is resolved to the fully qualified name of the class A in this module. Reference to a location in the document (same source file) Rendering: Directives Code: \|ref\|\`Directives <chapter_directives>\` Semantics: Cross reference to a location in the same file (here: roles.rst). Reference to a non-existing location in the document Rendering: Nowhere Code: \|ref\|\`Nowhere <chapter_nowhere>\` Reference to a location in the document (different source file) Rendering: Introduction Code: \|ref\|\`Introduction <chapter_introduction>\` Semantics: Cross reference to a location in a different file (here: introduction.rst).
«Class»	B

Waterloo module context

Default module qualifier doc_cross_referencing ends here. New default: doc_errors.