MEP10 : cohérence de la docstring #

Statut #

Progrès

C'est toujours un effort en cours

Branches et demandes d'extraction #

Résumé #

matplotlib a beaucoup d'incohérence entre les docstrings. Cela rend non seulement la documentation plus difficile à lire, mais c'est plus difficile pour les contributeurs, car ils ne savent pas quelles spécifications suivre. Il devrait y avoir une convention de docstring claire qui soit suivie de manière cohérente.

L'organisation de la documentation de l'API est difficile à suivre. Certaines pages, telles que pyplot et axes, sont énormes et difficiles à parcourir. Il devrait plutôt y avoir de courts tableaux récapitulatifs qui renvoient à une documentation détaillée. De plus, certaines des docstrings elles-mêmes sont assez longues et contiennent des informations redondantes.

Construire la documentation prend beaucoup de temps et utilise un make.py script plutôt qu'un Makefile.

Descriptif détaillé #

Il existe un certain nombre de nouveaux outils et conventions disponibles depuis que matplotlib a commencé à utiliser Sphinx qui facilitent la vie. Voici une liste des modifications proposées aux docstrings, dont la plupart impliquent ces nouvelles fonctionnalités.

Format de chaîne de documentation numérique #

Format de docstring numpy : Ce format divise la docstring en sections claires, chacune ayant des règles d'analyse différentes qui rendent la docstring facile à lire à la fois en tant que texte brut et en tant que HTML. Nous pourrions envisager des alternatives ou inventer les nôtres, mais c'est un choix fort, car il est bien utilisé et compris dans la communauté Numpy/Scipy.

Références croisées #

La plupart des docstrings de matplotlib utilisent des "rôles" explicites lors de la liaison à d'autres éléments, par exemple : :func:`myfunction`. Depuis Sphinx 0.4, il existe un "default_role" qui peut être défini sur "obj", qui sera lié de manière polymorphe à un objet Python de n'importe quel type. Cela permet d'écrire à la `myfunction`place. Cela rend les docstrings beaucoup plus faciles à lire et à modifier en tant que texte brut. De plus, Sphinx permet de définir un module actuel, de sorte que des liens comme `~matplotlib.axes.Axes.set_xlim` peuvent être écrits sous la forme `~axes.Axes.set_xlim`.

Remplacer les signatures #

De nombreuses méthodes de matplotlib utilisent la syntaxe *argset **kwargspour gérer dynamiquement les arguments de mots clés acceptés par la fonction ou pour déléguer à une autre fonction. Ceci, cependant, n'est souvent pas utile comme signature dans la documentation. Pour cette raison, de nombreuses méthodes matplotlib incluent quelque chose comme :

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

Cela ne peut pas être analysé par Sphinx et est plutôt verbeux en texte brut. À partir de Sphinx 1.1, si la autodoc_docstring_signaturevaleur de configuration est définie sur True, Sphinx extraira une signature de remplacement de la première ligne de la docstring, permettant ceci :

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

La signature explicite remplacera celle de Python dans la documentation générée.

Lier plutôt que dupliquer #

De nombreuses docstrings incluent de longues listes de mots-clés acceptés en interpolant des éléments dans la docstring au moment du chargement. Cela rend les docstrings très longues. De plus, comme ces tables sont les mêmes dans de nombreuses docstrings, cela insère beaucoup d'informations redondantes dans les docs - en particulier un problème dans la version imprimée.

Ces tableaux doivent être déplacés vers les docstrings sur les fonctions dont le seul but est d'aider. Les docstrings qui font référence à ces tables doivent être liées à celles-ci, plutôt que de les inclure textuellement.

extension de résumé automatique #

L'extension de résumé automatique Sphinx doit être utilisée pour générer des tableaux récapitulatifs, qui renvoient à des pages de documentation distinctes. Certaines classes qui ont de nombreuses méthodes (par exemple Axes) doivent être documentées avec une méthode par page, tandis que les classes plus petites doivent avoir toutes leurs méthodes ensemble.

Exemples de liens vers la documentation pertinente #

Les exemples, bien qu'utiles pour illustrer l'utilisation d'une fonctionnalité, ne renvoient pas aux docstrings pertinentes. Cela pourrait être résolu en ajoutant des docstrings au niveau du module aux exemples, puis en incluant cette docstring dans le contenu analysé sur la page d'exemple. Ces docstrings pourraient facilement inclure des références à toute autre partie de la documentation.

Documentation utilisant help() par rapport à un navigateur #

L'utilisation du balisage Sphinx dans la source permet d'obtenir de beaux documents dans votre navigateur, mais le balisage rend également le texte brut renvoyé à l'aide de help() terrible. L'un des objectifs de l'amélioration des docstrings devrait être de faire en sorte que les deux méthodes d'accès aux docs soient belles.

Mise en œuvre #

  1. Les extensions numpydoc doivent être activées pour matplotlib. Il y a une question importante à savoir si ceux-ci doivent être inclus dans l'arborescence source de matplotlib ou utilisés comme dépendance. L'installation de Numpy n'est pas suffisante pour obtenir les extensions numpydoc - c'est une procédure d'installation distincte. Dans tous les cas, dans la mesure où ils nécessitent une personnalisation pour nos besoins, nous devons nous efforcer de soumettre ces modifications en amont et de ne pas les forker.

  2. Parcourez manuellement toutes les docstrings et mettez-les à jour avec le nouveau format et les nouvelles conventions. La mise à jour des références croisées (de `:func:`myfunc`à `func`) peut éventuellement être semi-automatisée. C'est beaucoup de travail, et peut-être que ce travail devrait être divisé par module afin qu'aucun développeur ne soit surchargé.

  3. Réorganisez les documents de l'API à l'aide de la synthèse automatique et des fichiers sphinx-autogen. Cela devrait, espérons-le, avoir un impact minimal sur la documentation narrative.

  4. Modifiez le générateur de page d'exemple ( gen_rst.py) afin qu'il extraie la docstring du module de l'exemple et l'inclue dans une partie non littérale de la page d'exemple.

  5. Utilisez sphinx-quickstartpour générer un Makefile Sphinx de nouveau style. Les fonctionnalités suivantes dans le courant make.pydevront être traitées d'une autre manière :

    • Copie de certains contenus statiques

    • Spécification d'une "petite" version (uniquement des fichiers PNG basse résolution pour des exemples)

Les étapes 1, 2 et 3 sont interdépendantes. 4 et 5 peuvent être effectués indépendamment, bien que 5 dépende quelque peu de 3.

Rétrocompatibilité #

Comme cela implique principalement des docstrings, il devrait y avoir un impact minimal sur la rétrocompatibilité.

Alternatives #

Pas encore discuté.