Setup documentation

[zeakey]

@moliflower

Add docstrings to public morphological functions

Background

We just set up a documentation site (MkDocs + mkdocstrings) that auto-generates API
reference pages directly from Python docstrings. No separate doc files are needed —
the docstring in the source code is the documentation.

The site is structured as:

• docs/api/distance_transforms.md — renders euclidean_distance_transform,
  chamfer_distance_transform, brute_force_distance_transform
• docs/api/morphological_ops.md — renders binary_dilation, binary_erosion

The distance transform functions in torchmorph/distance_transform.py are already
fully documented and serve as the style reference. This PR covers the remaining
public functions.

Tasks

• Add a full docstring to binary_dilation in torchmorph/dilation_erosion.py
• Add a full docstring to binary_erosion in torchmorph/dilation_erosion.py
• completely remove the add function which was created for illustration.

Current state

binary_dilation and binary_erosion currently have no docstrings:

# torchmorph/dilation_erosion.py  (lines 316-321)
def binary_dilation(input_tensor, structure=None, iterations=1, origin=0, border_value=0):
    return _morph_op(input_tensor, structure, iterations, origin, border_value, mode="dilation")

def binary_erosion(input_tensor, structure=None, iterations=1, origin=0, border_value=0):
    return _morph_op(input_tensor, structure, iterations, origin, border_value, mode="erosion")

add has only a placeholder:

# torchmorph/add.py
def add(input: torch.Tensor, scalar: float) -> torch.Tensor:
    """Add the input tensor by a scalar using CUDA."""

Docstring conventions

Follow the Google style used throughout torchmorph/distance_transform.py.
Every public function docstring must have these sections, in this order:

1. Summary line — one sentence, imperative mood, no trailing period
2. Extended description — optional, 1–3 sentences on algorithm/behavior
3. Args: — one entry per parameter, include type and description
4. Returns: — describe return type and value; match the actual return annotation
5. Example: — at least one runnable snippet using >>> prefix

Args to cover for binary_dilation / binary_erosion

All five parameters must be documented. The private _morph_op and its helpers
contain the behavioral details — read those for accuracy:

Parameter	Type	Notes
input_tensor	torch.Tensor	Binary input; non-zero = foreground. Accepted shapes: (H, W), (C, H, W), (B, C, H, W), (B, C, D, H, W)
structure	Optional[torch.Tensor]	Structuring element. None → full 3×3 (or 3×3×3) connectivity, matching scipy default
iterations	int	Number of times the operation is applied sequentially
origin	int | Sequence[int]	Anchor point of the structuring element; scalar is broadcast to all spatial dims
border_value	int	Value assumed outside image boundary during padding (0 or 1)

Return type is torch.Tensor with dtype=torch.bool.

Example structure to follow

Look at euclidean_distance_transform in torchmorph/distance_transform.py for
the exact format. A minimal pattern:

def binary_dilation(input_tensor, structure=None, iterations=1, origin=0, border_value=0):
    """<Summary line>

    <Optional extended description.>

    Args:
        input_tensor: ...
        structure: ...
        iterations: ...
        origin: ...
        border_value: ...

    Returns:
        ...

    Example:
        >>> import torch
        >>> import torchmorph as tm
        >>> x = torch.zeros(1, 1, 5, 5)
        >>> x[0, 0, 2, 2] = 1
        >>> tm.binary_dilation(x)
        ...
    """
    return _morph_op(input_tensor, structure, iterations, origin, border_value, mode="dilation")

How to verify

Install the docs dependencies and preview locally:

pip install -r requirements-docs.txt
mkdocs serve

Open http://127.0.0.1:8000/tm/docs/api/morphological_ops/ and confirm that:

• Both binary_dilation and binary_erosion render with all sections
• Args table lists all five parameters with types and descriptions
• The example block is syntax-highlighted

Out of scope

• Private helpers (_morph_op, _normalize_structure, etc.) already have docstrings;
  do not modify them
• No changes to mkdocs.yml or docs/ are needed — the wiring is already in place