Exemple docstring

Ils devraient vraiment tenir sur une ligne. Pour plus de détails, consultez la documentation du Sphinx. Ce document a été placé dans le domaine public. La DocString entière est en retrait les mêmes que les guillemets à sa première ligne. Déclaration de chaînes: les chaînes sont déclarés à l`aide de “” “triple guillemets doubles” “” juste au-dessous de la classe, la méthode ou la déclara tion de fonction. Il contient une section sur docstrings, qui fait référence à PEP-257–une spécification complète pour docstrings. Le texte “spécification” vient surtout textuellement de l`essai de Python style Guide [4] de Guido van Rossum. Les guillemets triples sont utilisés même si la chaîne s`adapte sur une ligne. ReStructuredText est un langage de balisage, tout comme Markdown, qui a été utilisé pour documenter le code (entre autres usages). Pour en savoir plus, visitez http://sphinx. Les chaînes de documentation Python (ou docstrings) offrent un moyen pratique d`associer la documentation aux modules, fonctions, classes et méthodes Python. Pour que cela fonctionne, les chaînes doivent bien sûr être écrites en reStructuredText correct. Les arguments facultatifs doivent être indiqués.

Si la classe est destinée à être sous-classée et a une interface supplémentaire pour les sous-classes, cette interface doit être répertoriée séparément (dans la DocString). Les URL sont automatiquement liées, comme http://packages. Pour les docstrings Unicode, utilisez u “” “Unicode triple-guillemets chaînes” “”. Et peut-être-ignorer = D100, D101, D102, D103, D104 (voir la liste complète des codes d`erreur ici) pour se concentrer sur le polissage de vos chaînes existants avant de vous soucier de remplir les blancs. Tout style de documentation peut être utilisé avec les doctests, à condition d`ajouter un petit appel à la fin du fichier, l`exemple suivant (appelons-le doctest-example. Toutefois, chaînes semblent être beaucoup plus personnelle que d`autres domaines de code. L`exemple ci-dessous montre comment déclarer et accéder à une DocString. Il est largement utilisé dans la communauté scientifique.

L`idée derrière les directives d`auto est de conserver autant de documentation dans le code chaînes que possible. Vous vous demandez si votre propre code est conforme à PEP 257? Il s`agit du fichier qui contrôle les bases de la façon dont le Sphinx s`exécute lorsque vous exécutez une build. Les gens aiment vraiment naviguer et rechercher de la documentation sur le Web. Cependant, cela peut être un peu difficile à lire dans la DocString elle-même (une ligne de pensée est que le balisage Sphinx ne doit pas tuer la DocString qu`un utilisateur peut lire à travers l`attribut _ _ doc_). La docchaîne d`une ligne ne doit pas être une «signature» réitérant les paramètres de fonction/méthode (qui peut être obtenue par introspection). C`est python; quelque chose se passe. Datacamp fournit des cours interactifs en ligne qui combinent des défis de codage interactifs avec des vidéos des meilleurs instructeurs sur le terrain. De cette façon, la commande de remplissage-paragraphe Emacs peut être utilisée sur elle. Il n`y a pas de meilleure façon d`apprendre les subtilités que d`aller à la source de la vérité. Comme apparamment personne ne l`a mentionné: vous pouvez également utiliser le numpy DocString standard. La ligne récapitulative peut être utilisée par les outils d`indexation automatique; Il est important qu`il s`adapte sur une ligne et est séparé du reste de la DocString par une ligne vide. Le but de ce PEP est de normaliser la structure de haut niveau de docstrings: ce qu`ils doivent contenir, et comment dis-le (sans toucher à une syntaxe de balisage dans docstrings).

De nos jours, le format probablement plus répandu est le format reStructuredText (reST) qui est utilisé par Sphinx pour générer de la documentation. La syntaxe du Sphinx (tirée de http://sphinx. Si vous exécutez cet exemple avec l`indicateur détaillé (exemple Python doctest. Cependant, Sphinx vise toujours à vous donner le contrôle n`est pas trouvé lors de l`utilisation de vrais outils auto comme doxygen ou epydoc.

Comments are closed.