PEP256 ou ce que sont les docstrings

Python se prête bien à la documentation en ligne. Grâce à la syntaxe intégrée de la docstring, une forme limitée de programmation littérale est facile à réaliser en Python. Cependant, il n'existe pas d'outils standards satisfaisants pour extraire et traiter les docstrings Python. L'absence d'un ensemble d'outils standard est une lacune importante dans l'infrastructure de Python ; ce PEP vise à combler cette lacune.

Les questions relatives au traitement des docstrings ont été controversées et difficiles à résoudre. Ce PEP propose un cadre générique pour le système de traitement de la docstring (DPS), qui sépare les composants (programme et conceptuel), permettant la résolution des problèmes individuels soit par consensus (une solution) soit par divergence (plusieurs). Il promeut des interfaces standard qui permettront l'utilisation d'une variété de composants enfichables (lecteurs de contexte d'entrée, analyseurs de balisage et rédacteurs de format de sortie).

Au cours du temps, de nombreuses solutions ont été créées, mais aucune méthode n’était utilisables de façon généralisée et simple. Un consensus a donc été mis en œuvre pour trouver une façon de générer des documentations similaires à la javadoc de Java, par exemple, mais en version plus pythonique. La solution approuvée s’appuie sur du langage ReST (ReStructuredText) et permet une description plus détaillée. C’est ce qu’on nomme les docstrings.