web-dev-qa-db-fra.com

Comment créer une documentation avec Pydoc?

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

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

Cela a amené mon shell à être rempli de texte, une ligne pour chaque fichier de mon module, en disant:

no Python documentation found for '<file_name>'

C'est comme si Pydoc essayait d'obtenir de la documentation pour mes fichiers, mais je veux la créer automatiquement. Je ne pouvais pas trouver un bon tutoriel en utilisant Google. Quelqu'un a-t-il des conseils pour utiliser Pydoc?

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

python ... -w myModule\myFile.py

ça dit wrote myFile.html, et quand je l’ouvre, il y a une ligne de texte disant:

# ../myModule/myFile.py

En outre, il contient un lien vers le fichier lui-même sur mon ordinateur, sur lequel je peux cliquer et il affiche le contenu du fichier sur mon navigateur Web.

pythondocumentationpython-3.xdocumentation-generationpydoc
58
user1632861

Comme suggéré par RocketDonkey, votre module lui-même doit disposer de docstrings.

Par exemple, dans myModule/__init__.py:

"""
The mod module
"""

Vous souhaitez également générer de la documentation pour chaque fichier dans myModule/*.py en utilisant

pydoc myModule.thefilename

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

32
michel-slm

Une autre chose que les gens peuvent trouver utile… assurez-vous de laisser ".py" dans le nom de votre module. Par exemple, si vous essayez de générer de la documentation pour 'original' dans 'original.py':

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

yourcode_dir$ pydoc -w original
wrote original.html
83
Taylor

pydoc est fantastique pour générer de la documentation, mais la documentation doit être écrite en premier lieu. Vous devez avoir des docstrings dans votre code source, comme mentionné par 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 __== '__main__':
    f = Foo('John Doe', 42)
    bar("hello world")

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

73
zzzirk