8. Admonitions¶

The Waterloo extension can render diagnostics and context changes directly into the generated document. This is especially useful while writing documentation: the message appears close to the directive that caused it, instead of only being visible in the terminal output.

This chapter intentionally contains broken directives and invalid docstrings. The resulting admonitions are part of the showcase.

8.1. Error Admonitions¶

Error admonitions report directive misuse, unresolved objects, missing docstrings, and Waterloo parsing or validation errors. They are controlled by wtrl_diagnostics_admonitions_enabled.

8.1.1. Inappropriate Directive¶

The following directive asks for a class, but the identifier resolves to a module. The renderer therefore emits a directive diagnostic instead of trying to render the module as a class.

Error

Object: doc_errors

Summary: doc_errors does not resolve to a class.

8.1.2. Pop On Empty Stack¶

The context stacks are checked strictly. Popping the current module while the module stack is empty produces a diagnostic admonition.

Error

Summary: Cannot pop current module: stack is empty.

8.1.3. Push/Pop Mismatch¶

Pop directives require the value that is expected at the top of the stack. This turns accidental nesting mistakes into visible diagnostics.

Waterloo module context

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

Error

Summary: Module stack push/pop mismatch: expected doc_errors, got doc_errors_wrong.

8.1.4. Non-Existing Object¶

If the identifier cannot be resolved, the renderer reports the failed object lookup at the directive location.

Error

Object: doc_errors.X_does_not_exist

Summary: doc_errors.X_does_not_exist cannot be resolved: Could not resolve qualified name ‘doc_errors.X_does_not_exist’ with module/class context doc_errors/None.

8.1.5. Missing Docstring¶

An object without a docstring cannot be rendered as Waterloo documentation. The directive therefore emits a diagnostic instead of silently producing no output.

Error

Object: doc_errors.X_no_docstring

Summary: doc_errors.X_no_docstring has no docstring.

8.1.6. Empty Docstring¶

An empty docstring is treated like a missing documentation body and is reported explicitly.

Error

Object: doc_errors.X_empty_docstring

Summary: doc_errors.X_empty_docstring has no docstring.

8.1.7. Not A Waterloo Docstring¶

The following class has a Python docstring, but the text is not a valid Waterloo docstring. The parser diagnostic is shown in the generated document.

Error

RuleID: PRSR-003

Origin: parsing

Summary: missing colon in section or subsection label: expected a label ending with ‘:’, but found ‘Some text that is not a Waterloo Docstring.’.

Found:

Some text that is not a Waterloo Docstring.

Expected:

<a section or subsection label ending with ':'>

Hint:

["Append ':' to the label."]

8.1.8. Parsing Or Validation Error¶

The next example is syntactically close to a Waterloo docstring, but its content fails validation. The rendered admonition preserves the structured Waterloo diagnostic, including rule id, found/expected information, and hint.

Error

RuleID: CON-023

Origin: validation

Summary: Subsection ‘general’ does not exist.

Found:

Contract:

Expected:

Contract:
    general:
        ...

Hint:

waterlint explain-subsection --label Contract.general --profile class

8.2. Info Admonitions¶

Not every rendered admonition indicates an error. Some messages describe intentional omissions or visible state changes.

8.2.1. Out Of Scope¶

The following object exists and has a Waterloo docstring, but it is assigned a scope that is not visible under the current documentation scope. If wtrl_scope_filtered_object_placeholders_enabled is enabled, the renderer leaves a placeholder admonition instead of removing the object without a trace.

Note

Scope filter: skipped X_not_in_public_scope (object: extension; active: public).

8.3. State-Change Admonitions¶

State-changing directives can also be rendered into the document. This is controlled by wtrl_state_change_admonitions_enabled.

The following sequence shows module and class context changes as they appear in the generated document.

Waterloo module context

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

Waterloo class context

Methods below this point implicitly belong to class X_no_docstring.

Waterloo class context

Default class qualifier X_no_docstring ends here. No default class active.

Waterloo module context

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