Wie erstelle ich mit Pydoc Dokumentation?

74

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.

Lio
quelle
pydoc -w moduleNamefunktioniert bei mir für ein einzelnes Modul mit einer Funktion darin. Können Sie versuchen, ein einfaches Beispiel zu erstellen, das dies reproduziert? Ein Verzeichnislayout und der Inhalt der Dateien, und wo führen Sie welchen Befehl aus?
Millimoose
2
Entschuldigung im Voraus, wenn dies eine dumme Frage ist, aber haben Sie docstrings / etc. in deinem Modul? Bedeutet das, dass Sie den Inhalt in Ihrer Quelldatei haben, den das Ausführen pydocerzeugen soll?
RocketDonkey
Für diejenigen, die diese Seite nach einer kurzen Suchabfrage zum automatischen Generieren von Dokumentation in .pyDateien erreichen. Dafür ist nicht da pydoc. Pydoc ist für den Fall gedacht, dass Sie diese Dokumentation bereits geschrieben haben und sie hübsch machen möchten.
vor

Antworten:

35

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.

michel-slm
quelle
2
... Und wenn Sie haben Docstrings vorhanden, prüft , mit PDOC statt, weil es ein Ergebnis erzeugt , die näher an ist das, was heute die API - Dokumentation zu erwarten ist.
K3 --- rnc
97

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
Taylor
quelle
4
Ich frage mich, warum die akzeptierte Antwort dieses winzige Detail nicht liefert! Ohne .py fallen zu lassen, wird es zumindest in Py3 nicht funktionieren.
ThinkCode
Das hat geholfen. Ich habe auch festgestellt, dass wir uns beim Ausführen des pydoc im selben Verzeichnis befinden müssen ... dh wir können es nicht tun pydoc dir/prg.py. Wir müssen cd dirund dann tun pydoc prg.py. Ist das richtig?
Abhijithda
@abhijithda: Solange sich das Verzeichnis mit dem Modul in sys.path befindet, kann pydoc es tatsächlich finden.
Tom Barron
Dies war der hilfreichste Weg, dies zu tun. Ich weiß, dass dies geschlossen ist, aber zumindest in Python 2.7 kann ich jetzt Python -m pydoc Example_Pydoc (ohne die .py) ausführen und meine Dokumentation abrufen. Vielen Dank
Taku_
79

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.

zzzirk
quelle