Repenser la chaîne de documentation

Cet article est tiré du calendrier de l'Avent Maya-Python du 11 décembre.

introduction

L'une des fonctionnalités de Python est chaînes de documentation.

Il est interprété comme un document en écrivant les chaînes de caractères suivantes dans les modules, classes, fonctions, etc.

python

def sayhello():
    u"""Bonjour et dites bonjour gaiement."""
    sys.stdout.write(u"salut!")

Si vous le transmettez à la méthode d'aide, il sera formaté et généré, utilisez-le pour savoir comment utiliser la fonction.

>>> help(sayhello)
Help on function sayhello in module __main__:

sayhello()
Bonjour et dis bonjour joyeusement

Bien entendu, des modules standards sont également décrits.

>>> import os
>>> help(os.path.abspath)
Help on function abspath in module ntpath:

abspath(path)
    Return the absolute version of a path.

Environnement de vérification

Windows10 Python 2.7.12 PyCharm 2016.3 Sphinx 1.5 Maya 2016 Extension2

Les problèmes que nous avons

Nous gérons un grand nombre de modules, méthodes et classes sous forme de bibliothèques partagées. Même à ce moment, le nombre de fonctions est trop important pour tout se souvenir. Parmi ceux-ci, le package maya ne fonctionne qu'avec le Python intégré maya. Il existe d'autres packages dépendants de Python, mais cette fois, nous limiterons notre discussion à maya.

stu/
  __init__.py
  maya/
    __init__.py
    skin.py
Beaucoup d'autres ...
  path.py
  pyside.py
Beaucoup d'autres ...

• Promouvoir l'utilisation des bibliothèques partagées
• Évitez le réaménagement des roues

Pour les deux raisons ci-dessus, il existe un besoin pour un système qui peut être facilement recherché avec la fonction souhaitée et qui a une grande visibilité pour les spécifications des arguments de méthode.

Comme j'ai également créé un code de test, je peux comprendre comment l'utiliser en regardant le code de test, mais bien sûr, je ne sais pas comment les spécifications actuelles sont faites, et le code de test n'est pas bon en premier lieu. Assez souvent.

Donc, l'histoire est "laissons une note sur le docstring correctement", mais je ne l'écris pas moi-même de manière très agressive.

Les humains ont besoin de motivation pour agir.

Alors, comment vous motivez-vous? Je voudrais donc reconsidérer la docstring.

Problèmes non entretenus

Comme mentionné dans PEP8, le pire est que le code et les commentaires ne correspondent pas. Je ne sais pas lequel est correct. Il vaudrait mieux ne pas écrire de commentaires qui ne sont pas maintenus.

Pourquoi n'écrivez-vous pas simplement des excuses comme ça? N'est-ce pas simplement parce qu'il n'y a aucun avantage pour moi?

Python évolue de jour en jour. À partir de Python 3.5, une fonction pour définir le type d'une variable appelée Type Hints (PEP484) a été ajoutée. Il est possible de définir les types d'arguments et de valeurs de retour, et si l'éditeur le prend en charge, les méthodes des variables renvoyées peuvent être affichées comme candidates. Dans PyCharm, Type Hinting En tant que fonction, tapez Hints of Python3.5 et comment décrire dans docstrings Il semble le soutenir.

Cela semble être une incitation à maintenir la docstring.

Maintenant, je voudrais faire la vérification suivante et obtenir le document HTML tout en utilisant docstring commodément.

1. Indice de type PyCharm
2. Rechercher des documents en HTML avec Sphinx

Vérifier l'indication de type

Il semble que Type Hints ait été introduit dans Python 3.5, il semble donc qu'il existe un moyen de l'exprimer dans certains commentaires, mais comme il ne peut pas être utilisé dans Python 2, il est rejeté.

Tout d'abord, comme d'habitude, assurez-vous que l'Interprète de Projet est de la mayapy. Si cela est négligé, même si le type de pymel est défini, cela ne fonctionnera pas.

Définissons la valeur de retour de la fonction. Essayez de spécifier SkinCluster avec rtype` ``. Alors, essayez d'appeler la fonction et de la stocker dans une variable.

Si vous tapez une méthode à partir de cette variable ... la méthode de l'objet skinCluster sera candidate. Bien sûr, la méthode de la classe parent. Génial···

Maintenant, il n'y a aucune raison de ne pas écrire facilement rtype.

Valider Sphinx

Python dispose de plusieurs mécanismes pour générer automatiquement des documents HTML à partir du code source, mais récemment, il se concentre également sur le support des langages de programmation autres que Python Sphinx. /en/1.5/) est probablement le plus courant. La documentation officielle de Python lui-même est également Sphinx. Au contraire, il semble qu'il a été développé à cette fin.

Sphinx génère automatiquement un document afin que vous puissiez rechercher les informations écrites dans la docstring.

Pour le moment, installez sphinx avec pip.

"C:\Program Files\Autodesk\Maya2016\bin\mayapy.exe" -m pip install sphinx --user

Puisque Sphinx peut également être utilisé avec PyCharm, spécifiez le répertoire du document. Cette fois, c'est C: \ sample \ sphinx.

Exécutez Sphinx Quickstart pour créer un fichier de configuration de manière interactive. Fondamentalement, la langue est définie sur ja et le reste est OK par défaut. (Désolé pour l'explication approximative)

Avec cela seul, les docstrings ne sont pas pertinents et ne créent du HTML qu'à partir d'un fichier texte (.rst) au format reStructuredText, donc [sphinx-apidoc](http://www.sphinx-doc.org/ja/stable/invocation.html# Invocation-of-sphinx-apidoc) est utilisé séparément pour générer un fichier .rst qui génère une documentation API à partir du code source. Il sera exécuté sur la ligne de commande.

%USERPROFILE%\AppData\Roaming\Python\Scripts\sphinx-apidoc.chemin de la bibliothèque exe-o C:\sample\sphinx

Vous êtes maintenant prêt. Vient ensuite l'exécution de la génération de documents. Revenez à PyCharm et créez une nouvelle configuration à partir des configurations d'exécution / débogage. La tâche Python docs / Sphinx est correctement préparée ... Spécifiez l'entrée et la sortie et c'est fait. Je pense que Interpreter est de la mayapy, mais veuillez noter que Sphinx importe le module à documenter et obtient les docstrings, donc en Python normal, une erreur d'importation se produira et la documentation échouera également.

Alors, courez comme d'habitude. C: \ sample \ sphinx \ _ build \ index.html (et bien d'autres) doit être généré.

Ouvrez index.html. Dans l'état par défaut, le html est généré, mais cherchons-le.

Oh, le résultat est sorti. (L'un est les ordures)

Oh! Le type de retour décrit dans la docstring est décrit correctement.

Résumé

Beaucoup de savoir-faire pour les docstrings vient du Web. Il semble y avoir des candidats pour le format de balisage, mais pour le moment, je l'écrirai dans reStructuredText, qui est le balisage Python standard. Comme pour cette phrase écrite en Qiita, la démarque est-elle la norme de facto pour les langages de balisage dans le monde? Je suis un peu inquiet car ce n'est pas surprenant, mais je n'ai pas besoin de me précipiter vers la conclusion car le but n'est pas au départ un document avec une structure aussi compliquée. J'y penserai à un autre moment.

Sphinx semble un peu difficile à exécuter sur la ligne de commande, mais l'exécuter sur PyCharm cache la plupart des tracas. En fait, j'ai répété beaucoup d'essais et d'erreurs, et par conséquent, je suis un peu déçu que l'utilisation de PyCharm entraîne une procédure assassine.

En fin de compte, le résultat était à nouveau le meilleur de PyCharm.

référence

Maîtriser les indices de type dans PyCharm Documentation d'écriture facile dans Sphinx avec PyCharm (IntelliJ)