mod-003i-docstrings-should-include-cross-references

When writing docstrings with references to other code, rule MOD-003i should be followed. Explicitly reference "Following rule MOD-003i, which encourages cross-references using :class:, :func:, :meth:..." when adding links.

MOD-003i: Docstrings should include cross-references

Description:

When possible, docstrings should use links to other docstrings using Sphinx cross-reference syntax:

• Classes: :class:~physicsnemo.models.some_model.SomeModel``
• Functions: :func:~physicsnemo.utils.common_function``
• Methods: :meth:~physicsnemo.models.some_model.SomeModel.some_method``

When referencing external resources, such as papers, websites, or other documentation, docstrings should use links to the external resource in the format some link text <some_url>_.

Rationale:

Cross-references create a navigable documentation structure where users can easily jump between related classes, methods, and functions. External links provide context and attribution for algorithms and techniques. This improves the overall quality and usability of the documentation.

Example:

class MyEncoder(Module):
    r"""
    Encoder network using attention mechanism.

    This implementation is based on `Transformer Architecture <https://arxiv.org/abs/1706.03762>`_.
    See :class:`~physicsnemo.nn.MultiHeadAttention` for attention details.

    Parameters
    ----------
    activation : str
        Activation function. See :func:`~torch.nn.functional.relu` for details.

    Notes
    -----
    Can be paired with :class:`~physicsnemo.models.decoder.MyDecoder` for
    autoencoding tasks.
    """
    pass

Anti-pattern:

# Not necessarily wrong, but missing opportunities for useful links
class MyEncoder(Module):
    r"""
    Encoder network using attention mechanism.

    Based on the Transformer paper.  # Could link to paper
    Uses MultiHeadAttention.  # Could link to class
    """
    pass