Documenting¶

The documentation is built using Sphinx using the Furo theme. The documentation sources are organized as follows:

docs/: main documentation directory containing .md files (including this one).
docs/tutorials/: see Tutorials Gallery in Jupyter notebook format (.ipynb): these notebooks must be added to the docs/gallery.rst file.
docstrings in the codebase located in src/scimba_torch/: it is automatically extracted using the Sphinx autodoc extension to generate the API documentation.

Warning

Please read carefully this guide in order to ensure consistency and clarity in the documentation, otherwise your contributions might be rejected by the pre-commit hooks.
Do not hesitate to correct existing docstrings that do not follow the recommended style 🙏.

Build the documentation¶

Build and serve the documentation locally:

sphinx-autobuild docs/ docs/build/html --watch src/

Go to http://localhost:8000 and see the changes in docs/ and src/ directories take effect immediately.

Writing docstrings¶

When writing docstrings, follow the Google style guide for consistency and clarity.

Recommended Google Style Format¶

def example_function(param1: str, param2: int = 0) -> bool:
    """Short description of the function in one line.

    More detailed description if necessary, which can extend
    over multiple lines to explain the behavior.

    Args:
        param1: Description of the first parameter.
        param2: Description of the second parameter. Defaults to 0.

    Returns:
        Description of what the function returns.

    Raises:
        ValueError: When param1 is empty.
        TypeError: When param2 is not an integer.

    Example:
        >>> example_function("test", 5)
        True
    """

Common Conversions¶

Sphinx Style → Google¶

Before (Sphinx):

"""
Function description.

:param param1: description of parameter 1
:type param1: str
:param param2: description of parameter 2
:type param2: int
:return: description of return value
:rtype: bool
:raises ValueError: when error occurs
"""

After (Google):

"""Function description.

Args:
    param1: Description of parameter 1.
    param2: Description of parameter 2.

Returns:
    Description of return value.

Raises:
    ValueError: When error occurs.
"""

Mixed Style → Google¶

Before (mixed):

"""
Description

Parameters:
-----------
x : torch.Tensor
    coordinates
labels : torch.Tensor
    labels

Returns:
--------
torch.Tensor
    result
"""

After (Google):

"""Description.

Args:
    x: Coordinates.
    labels: Labels.

Returns:
    Result.
"""

These conversions can be automated using tools like docconvert and ruff, but manual review is recommended to ensure clarity and correctness.

Main Style Rules¶

First line: Short description that fits on one line
Blank line: After the short description
Args: 4-space indentation, name followed by :
Returns: Simple description without type (type hint is sufficient)
Raises: Exception type followed by :
No types: Type hints in the signature are sufficient, do not repeat types in docstrings

Project-specific Examples¶

Classes¶

class MyTensor:
    """Class for managing tensors with labels.

    Args:
        x: Tensor of coordinates.
        labels: Labels associated with coordinates.

    Attributes:
        x: Tensor of coordinates.
        labels: Labels of coordinates.
        dim: Dimension of the space.

    Raises:
        ValueError: If x has dimension <= 1.
    """

Magic Methods¶

def __add__(self, other):
    """Overload of the + operator.

    Args:
        other: Value or tensor to add.

    Returns:
        New LabelTensor resulting from the addition.

    Raises:
        ValueError: If labels don't match.
    """

Methods with Optional Parameters¶

def get_components(self, label: int | None = None) -> torch.Tensor | tuple[torch.Tensor]:
    """Retrieve tensor components.

    Args:
        label: Specific label to extract. If None, returns all components.

    Returns:
        If label specified, tensor of the selected dimension.
        If label=None, tuple of tensors for all dimensions.

    Raises:
        ValueError: If no coordinate with this label is found.
    """

Tools¶

If required, use docconvert that converts docstrings to google style:

docconvert -o google --in-place path/to/your_file_or_directory

Verification with:
- ruff (and its VSCode extension) that will raise errors according to the [tool.ruff*] section in pyproject.toml:
```
ruff check
```
- pydoclint (and its VSCode extension) that will raise errors according to the [tool.pydoclint] section in pyproject.toml:
```
pydoclint path/to/your_file_or_directory
```
Manual review and editing until ruff and pydoclint pass without errors.
Documentation generated with Sphinx Napoleon extension (See above).