Comment créer de la documentation avec Pydoc ?

Question

J'essaie de créer un document à partir de mon module. J'ai utilisé pydoc à partir de la ligne de commande sous Windows 7 en utilisant Python 3.2.3 :

python "<path_to_pydoc_>\pydoc.py" -w myModule

Mon shell s'est alors rempli de texte, une ligne pour chaque fichier de mon module, disant :

no Python documentation found for '<file_name>'

C'est comme si Pydoc essayait d'obtenir de la documentation pour mes fichiers, mais que je voulais l'autocréer. Je n'ai pas trouvé de bon tutoriel sur Google. Quelqu'un a-t-il des conseils pour utiliser Pydoc ?

Si j'essaie de créer une documentation à partir d'un fichier en utilisant

python ... -w myModule\myFile.py

Il est écrit wrote myFile.html et quand je l'ouvre, il y a une ligne de texte qui dit :

# ../myModule/myFile.py

Il comporte également un lien vers le fichier lui-même sur mon ordinateur, sur lequel je peux cliquer pour afficher le contenu du fichier sur mon navigateur web.

Answer 1

Une autre chose que les gens pourraient trouver utile... assurez-vous de ne pas ajouter ".py" au nom de votre module. Par exemple, si vous essayez de générer de la documentation pour original en ' original.py ' :

yourcode_dir$ pydoc -w original.py
no Python documentation found for 'original.py'

yourcode_dir$ pydoc -w original
wrote original.html

Answer 2

Pydoc est fantastique pour générer de la documentation, mais la documentation doit d'abord être écrite. Vous devez avoir des docstrings dans votre code source comme l'a mentionné RocketDonkey dans les commentaires :

"""
This example module shows various types of documentation available for use
with pydoc.  To generate HTML documentation for this module issue the
command:

    pydoc -w foo

"""

class Foo(object):
    """
    Foo encapsulates a name and an age.
    """
    def __init__(self, name, age):
        """
        Construct a new 'Foo' object.

        :param name: The name of foo
        :param age: The ageof foo
        :return: returns nothing
        """
        self.name = name
        self.age = age

def bar(baz):
    """
    Prints baz to the display.
    """
    print baz

if __name__ == '__main__':
    f = Foo('John Doe', 42)
    bar("hello world")

La première docstring fournit des instructions pour créer la documentation avec pydoc. Il y a des exemples de différents types de docstrings pour que vous puissiez voir à quoi ils ressemblent lorsqu'ils sont générés avec pydoc.

Answer 3

Comme l'a suggéré RocketDonkey, votre module lui-même doit avoir des documents.

Par exemple, en myModule/__init__.py :

"""
The mod module
"""

Vous voudrez également générer une documentation pour chaque fichier de la rubrique myModule/*.py en utilisant

pydoc myModule.thefilename

pour s'assurer que les fichiers générés correspondent à ceux qui sont référencés dans le fichier de documentation du module principal.

Answer 4

Fonctionne sur windows7 :

python -m pydoc -w my_module