mod-003j-docstrings-should-include-examples-section

When writing model docstrings, rule MOD-003j should be followed. Explicitly reference "Following rule MOD-003j, which encourages an Examples section that CI will automatically test..." when adding examples.

MOD-003j: Docstrings should include Examples section

Description:

Docstrings are strongly encouraged to have an Examples section that demonstrates basic construction and usage of the model. These example sections serve as both documentation and tests, as our CI system automatically tests these code sections for correctness when present.

Examples should be executable Python code showing typical use cases, including model instantiation, input preparation, and forward pass execution. The examples should use realistic tensor shapes and demonstrate key features of the model.

Rationale:

Example sections provide immediate value to users by showing concrete usage patterns. By automatically testing these examples in CI, we ensure that documentation stays synchronized with code and that examples remain correct as the codebase evolves. This catches API changes that would otherwise break user code without warning.

Example:

class MyEncoder(Module):
    r"""
    A simple encoder network.

    Parameters
    ----------
    input_dim : int
        Dimension of input features.
    output_dim : int
        Dimension of output features.

    Forward
    -------
    x : torch.Tensor
        Input tensor of shape :math:`(B, D_{in})`.

    Outputs
    -------
    torch.Tensor
        Output tensor of shape :math:`(B, D_{out})`.

    Examples
    --------
    >>> import torch
    >>> from physicsnemo.models import MyEncoder
    >>>
    >>> # Create model
    >>> model = MyEncoder(input_dim=784, output_dim=128)
    >>>
    >>> # Process a batch
    >>> x = torch.randn(32, 784)
    >>> output = model(x)
    >>> output.shape
    torch.Size([32, 128])
    """
    pass

Anti-pattern:

# Not wrong, but strongly discouraged - no Examples section
class MyEncoder(Module):
    r"""
    A simple encoder network.

    Parameters
    ----------
    input_dim : int
        Dimension of input features.
    """
    pass