Wie erstelle ich mit Pydoc Dokumentation?

Ich versuche, aus meinem Modul ein Dokument zu erstellen. Ich habe pydocüber die Befehlszeile in Windows 7 Python 3.2.3 verwendet:

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

Dies führte dazu, dass meine Shell mit Text gefüllt wurde, einer Zeile für jede Datei in meinem Modul, in der stand:

no Python documentation found for '<file_name>'

Es ist, als würde Pydoc versuchen, Dokumentation für meine Dateien zu erhalten, aber ich möchte sie automatisch erstellen. Ich konnte mit Google kein gutes Tutorial finden. Hat jemand Tipps zur Verwendung von Pydoc?

Wenn ich versuche, Dokumentation aus einer Datei mit zu erstellen

python ... -w myModule\myFile.py

es heißt wrote myFile.html, und wenn ich es öffne, steht in einer Textzeile:

# ../myModule/myFile.py

Außerdem enthält es einen Link zur Datei selbst auf meinem Computer, auf den ich klicken kann, und zeigt an, was sich in der Datei meines Webbrowsers befindet.

Wie von RocketDonkey vorgeschlagen, muss Ihr Modul selbst über einige Dokumentzeichenfolgen verfügen.

Zum Beispiel in myModule/__init__.py:

"""
The mod module
"""

Sie würden auch die Dokumentation für jede Datei in generieren wollen myModule/*.pymit

pydoc myModule.thefilename

um sicherzustellen, dass die generierten Dateien mit denen übereinstimmen, auf die in der Dokumentationsdatei des Hauptmoduls verwiesen wird.

Eine andere Sache, die die Leute vielleicht nützlich finden ... stellen Sie sicher, dass Sie ".py" in Ihrem Modulnamen weglassen. Wenn Sie beispielsweise versuchen, eine Dokumentation für 'original' in ' original.py ' zu generieren :

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

yourcode_dir$ pydoc -w original
wrote original.html

pydoc ist fantastisch zum Generieren von Dokumentation, aber die Dokumentation muss zuerst geschrieben werden. Sie müssen Docstrings in Ihrem Quellcode haben, wie von RocketDonkey in den Kommentaren erwähnt:

"""
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")

Die erste Dokumentzeichenfolge enthält Anweisungen zum Erstellen der Dokumentation mit pydoc. Es gibt Beispiele für verschiedene Arten von Dokumentzeichenfolgen, damit Sie sehen können, wie sie aussehen, wenn sie mit pydoc generiert werden.