Guide de rédaction des docstrings PyTorch

Ce skill décrit comment rédiger des docstrings pour les fonctions et méthodes du projet PyTorch, en suivant les conventions de torch/_tensor_docs.py et torch/nn/functional.py.

Principes généraux

• Utilisez des chaînes brutes (r"""...""") pour tous les docstrings afin d'éviter les problèmes avec les antislashs LaTeX/mathématiques
• Suivez le format Sphinx/reStructuredText (reST) pour la documentation
• Soyez concis mais complet - incluez toutes les informations essentielles
• Incluez toujours des exemples quand c'est possible
• Utilisez des références croisées vers les fonctions/classes connexes

Structure du docstring

1. Signature de fonction (première ligne)

Commencez par la signature de la fonction avec tous les paramètres :

r"""function_name(param1, param2, *, kwarg1=default1, kwarg2=default2) -> ReturnType

Notes :

• Incluez le nom de la fonction
• Montrez les arguments positionnels et les arguments nommés seulement (utilisez le séparateur *)
• Incluez les valeurs par défaut
• Affichez l'annotation du type de retour
• Cette ligne ne doit PAS se terminer par un point

2. Brève description

Fournissez une description d'une ligne de ce que la fonction fait :

r"""conv2d(input, weight, bias=None, stride=1, padding=0, dilation=1, groups=1) -> Tensor

Applique une convolution 2D sur une image d'entrée composée de plusieurs
plans d'entrée.

3. Formules mathématiques (le cas échéant)

Utilisez les directives math Sphinx pour les expressions mathématiques :

.. math::
    \text{Softmax}(x_{i}) = \frac{\exp(x_i)}{\sum_j \exp(x_j)}

Ou math en ligne : :math:\x^2``

4. Références croisées

Créez des liens vers les classes et fonctions connexes en utilisant les rôles Sphinx :

• :class:\~torch.nn.ModuleName`` - Lien vers une classe
• :func:\torch.function_name`` - Lien vers une fonction
• :meth:\~Tensor.method_name`` - Lien vers une méthode
• :attr:\attribute_name`` - Référence un attribut
• Le préfixe ~ affiche uniquement le dernier composant (par exemple, Conv2d au lieu de torch.nn.Conv2d)

Exemple :

Voir :class:`~torch.nn.Conv2d` pour les détails et la forme de la sortie.

5. Notes et avertissements

Utilisez les admonitions pour les informations importantes :

.. note::
    Cette fonction ne fonctionne pas directement avec NLLLoss,
    qui s'attend à ce que le Log soit calculé entre Softmax et lui-même.
    Utilisez log_softmax à la place (c'est plus rapide et a de meilleures propriétés numériques).

.. warning::
    :func:`new_tensor` copie toujours :attr:`data`. Si vous avez un Tensor
    ``data`` et voulez éviter une copie, utilisez :func:`torch.Tensor.requires_grad_`
    ou :func:`torch.Tensor.detach`.

6. Section Args

Documentez tous les paramètres avec les annotations de type et les descriptions :

Args:
    input (Tensor): tenseur d'entrée de forme :math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`
    weight (Tensor): filtres de forme :math:`(\text{out\_channels} , kH , kW)`
    bias (Tensor, optional): tenseur de biais optionnel de forme :math:`(\text{out\_channels})`. Default: ``None``
    stride (int or tuple): le pas du noyau de convolution. Peut être un nombre unique ou un
      tuple `(sH, sW)`. Default: 1

Règles de formatage :

• Nom du paramètre en minuscules
• Type entre parenthèses : (Type), (Type, optional) pour les paramètres optionnels
• La description suit le type
• Pour les paramètres optionnels, incluez « Default: value » à la fin
• Utilisez des double backticks pour le code en ligne : ``None``
• Indentez les lignes de continuation de 2 espaces

7. Section Keyword Args (le cas échéant)

Parfois, les arguments nommés sont documentés séparément :

Keyword args:
    dtype (:class:`torch.dtype`, optional): le type souhaité du tenseur retourné.
        Default: si None, le même :class:`torch.dtype` que ce tenseur.
    device (:class:`torch.device`, optional): l'appareil souhaité du tenseur retourné.
        Default: si None, le même :class:`torch.device` que ce tenseur.
    requires_grad (bool, optional): Si autograd doit enregistrer les opérations sur le
        tenseur retourné. Default: ``False``.

8. Section Returns (si nécessaire)

Documentez la valeur de retour :

Returns:
    Tensor: Tenseur échantillonné de la même forme que `logits` à partir de la distribution Gumbel-Softmax.
        Si ``hard=True``, les échantillons retournés seront one-hot, sinon ils seront
        des distributions de probabilité qui somment à 1 selon `dim`.

Ou incluez-le simplement dans la ligne de signature de la fonction si c'est évident d'après le contexte.

9. Section Examples

Incluez toujours des exemples si possible :

Examples::

    >>> inputs = torch.randn(33, 16, 30)
    >>> filters = torch.randn(20, 16, 5)
    >>> F.conv1d(inputs, filters)

    >>> # Avec noyaux carrés et stride égal
    >>> filters = torch.randn(8, 4, 3, 3)
    >>> inputs = torch.randn(1, 4, 5, 5)
    >>> F.conv2d(inputs, filters, padding=1)

Règles de formatage :

• Utilisez Examples:: avec double deux-points
• Utilisez l'invite >>> pour le code Python
• Incluez les commentaires avec # quand c'est utile
• Montrez la sortie réelle quand cela aide à la compréhension (indentez sans >>>)

10. Références externes

Créez des liens vers les articles ou la documentation externe :

.. _Link Name:
    https://arxiv.org/abs/1611.00712

Référencez-les dans le texte : Voir `Link Name`_

Types de méthodes

Fonctions Python natives

Pour les fonctions Python ordinaires, utilisez un docstring standard :

def relu(input: Tensor, inplace: bool = False) -> Tensor:
    r"""relu(input, inplace=False) -> Tensor

    Applique la fonction linéaire rectifiée élément par élément. Voir
    :class:`~torch.nn.ReLU` pour plus de détails.
    """
    # implementation

Fonctions liées à C (utilisant add_docstr)

Pour les fonctions liées à C, utilisez _add_docstr :

conv1d = _add_docstr(
    torch.conv1d,
    r"""
conv1d(input, weight, bias=None, stride=1, padding=0, dilation=1, groups=1) -> Tensor

Applique une convolution 1D sur un signal d'entrée composé de plusieurs
plans d'entrée.

Voir :class:`~torch.nn.Conv1d` pour les détails et la forme de la sortie.

Args:
    input: tenseur d'entrée de forme :math:`(\text{minibatch} , \text{in\_channels} , iW)`
    weight: filtres de forme :math:`(\text{out\_channels} , kW)`
    ...
""",
)

Variantes in-place

Pour les opérations in-place (se terminant par _), référencez l'original :

add_docstr_all(
    "abs_",
    r"""
abs_() -> Tensor

Version in-place de :meth:`~Tensor.abs`
""",
)

Fonctions alias

Pour les alias, référencez simplement l'original :

add_docstr_all(
    "absolute",
    r"""
absolute() -> Tensor

Alias pour :func:`abs`
""",
)

Motifs courants

Documentation des formes

Utilisez la notation mathématique LaTeX pour les formes de tenseurs :

:math:`(\text{minibatch} , \text{in\_channels} , iH , iW)`

Définitions d'arguments réutilisables

Pour les arguments couramment utilisés, définissez-les une fois et réutilisez-les :

common_args = parse_kwargs(
    """
    dtype (:class:`torch.dtype`, optional): le type souhaité du tenseur retourné.
        Default: si None, le même que ce tenseur.
"""
)

# Ensuite utilisez avec .format():
r"""
...

Keyword args:
    {dtype}
    {device}
""".format(**common_args)

Insertion de modèle

Insérez des notes de reproductibilité ou autre texte courant :

r"""
{tf32_note}

{cudnn_reproducibility_note}
""".format(**reproducibility_notes, **tf32_notes)

Exemple complet

Voici un exemple complet montrant tous les éléments :

def gumbel_softmax(
    logits: Tensor,
    tau: float = 1,
    hard: bool = False,
    eps: float = 1e-10,
    dim: int = -1,
) -> Tensor:
    r"""
    Échantillonnez à partir de la distribution Gumbel-Softmax et discrétisez optionnellement.

    Args:
        logits (Tensor): `[..., num_features]` log probabilités non normalisées
        tau (float): température scalaire non-négative
        hard (bool): si ``True``, les échantillons retournés seront discrétisés comme des vecteurs one-hot,
              mais seront différenciés comme s'il s'agissait de l'échantillon logiciel en autograd. Default: ``False``
        dim (int): Une dimension selon laquelle softmax sera calculée. Default: -1

    Returns:
        Tensor: Tenseur échantillonné de la même forme que `logits` à partir de la distribution Gumbel-Softmax.
            Si ``hard=True``, les échantillons retournés seront one-hot, sinon ils seront
            des distributions de probabilité qui somment à 1 selon `dim`.

    .. note::
        Cette fonction est ici pour des raisons héréditaires, pourrait être supprimée de nn.Functional à l'avenir.

    Examples::
        >>> logits = torch.randn(20, 32)
        >>> # Échantillonnez la catégorie logicielle en utilisant le truc de reparamétrisation :
        >>> F.gumbel_softmax(logits, tau=1, hard=False)
        >>> # Échantillonnez la catégorie dure en utilisant le truc « Straight-through » :
        >>> F.gumbel_softmax(logits, tau=1, hard=True)

    .. _Link 1:
        https://arxiv.org/abs/1611.00712
    """
    # implementation

Liste de contrôle rapide

Lors de la rédaction d'un docstring PyTorch, assurez-vous :

• [ ] Utiliser la chaîne brute (r""")
• [ ] Inclure la signature de la fonction sur la première ligne
• [ ] Fournir une brève description
• [ ] Documenter tous les paramètres dans la section Args avec les types
• [ ] Inclure les valeurs par défaut pour les paramètres optionnels
• [ ] Utiliser les références croisées Sphinx (:func:, :class:, :meth:)
• [ ] Ajouter des formules mathématiques si applicable
• [ ] Inclure au moins un exemple dans la section Examples
• [ ] Ajouter des avertissements/notes pour les mises en garde importantes
• [ ] Créer un lien vers la classe du module connexe avec :class:
• [ ] Utiliser la notation mathématique appropriée pour les formes de tenseurs
• [ ] Suivre un formatage et une indentation cohérents

Référence des rôles Sphinx courants

• :class:\~torch.nn.Module`` - Référence de classe
• :func:\torch.function`` - Référence de fonction
• :meth:\~Tensor.method`` - Référence de méthode
• :attr:\attribute`` - Référence d'attribut
• :math:\equation`` - Mathématiques en ligne
• :ref:\label`` - Référence interne
• ``code`` - Code en ligne (utiliser les double backticks)

Notes supplémentaires

• Indentation : Utilisez 4 espaces pour le code, 2 espaces pour la continuation des descriptions de paramètres
• Longueur de ligne : Essayez de garder les lignes sous 100 caractères si possible
• Points : Terminez les phrases avec des points, sauf la ligne de signature
• Backticks : Utilisez des double backticks pour le code : ``True`` ``None`` ``False``
• Types : Les types courants sont Tensor, int, float, bool, str, tuple, list, etc.