Documenter mon code Django

Question

Je viens de commencer un projet avec Django et je voulais écrire quelque chose comme l'extrait de javadoc ci-dessous pour une fonction Python. J'ai vu que je pouvais utiliser Sphinx ou reStructuredText mais cela me semble exagéré. Quelle est la façon normale de faire cela en Python ?

Mon objectif n'est pas de générer un gros pdf/html avec ma documentation, mais de faire en sorte que mon IDE (pyCharm) affiche les docs lorsque j'appelle mes méthodes.

 /**
  * 
  * @param p1
  * @param p2
  * @param p3
  * @return ...
  */

Answer 1

J'utilise intensivement IntellJ IDEA / PyCharm sur des projets Django et Python.

La voie à suivre est sans aucun doute reStructuredText et Sphinx, ce dernier uniquement si vous souhaitez générer une documentation HTML ou PDF. C'est également de cette façon que la bibliothèque Python elle-même est documentée. J'ai quitté epydoc pour reStructuredText il y a quelques mois, car le support général de ce dernier est bien meilleur.

Votre docstring ressemblerait à ceci :

def myfunc(p1, p2, p3):
    """myfunc does something interesting.

    some more detail. See :meth:`my_other_func` for more information.

    :param p1: The first parameter.
    :type p1: string
    :param p2: The second parameter.
    :param p3: The third parameter.
    :returns: True if successful, False if not.
    """

    my_code(p1)
    more_code(p2)
    return third_part(p1,p2,p3)

Il ne diffère pas beaucoup de l'ancien standard epydoc pour les éléments de base. PyCharm est capable d'analyser ces informations, par exemple en utilisant les spécifications :type : pour compléter le corps de votre fonction.

Answer 2

Comme mentionné dans le Aide web de PyCharm sur les formats de chaînes de caractères supportés vous aurez trois options :

• RestructuredText (rst) pour docutils . Vous n'êtes pas obligé d'utiliser Sphinx pour générer du HTML. Vous pouvez le garder aussi léger que vous le souhaitez.
• epytext format. (voir aussi : documentation des champs epydoc )
• en texte clair. Cela n'offre rien en termes de crochets de paramètres ou de valeurs de retour. PyCharm n'affichera que la docstring en clair.