Python pydoc für Python-Pakete

Question

Ich versuche, ein Python-Paket in init.py zu dokumentieren und es ist mir nicht klar, wie pydoc ein „“ „triple klammert“ parst „“ Kommentar für den Benutzer angezeigt werden über:

>>> help(package) 

oder

$ pydoc package 

Wie wird der Kommentar zur Bereitstellung von Inhalten in dem Namen und die Beschreibung Abschnitten der pydoc Ausgabe analysiert? Gibt es andere Abschnitte, die ich auch füllen kann, wie BEISPIELE?

Answer 1

Lassen Sie uns diese Dummy-Paket betrachten:

./whatever 
├── __init__.py 
├── nothing 
│   └── __init__.py 
└── something.py 

in ./whatever/__init__.py haben wir:

""" 
This is whatever help info. 

This is whatever description 

EXAMPLES: 
    ... 
""" 

__version__ = '1.0' 

variable = 'variable' 

Jetzt läuft Python-Shell:

➜ ~ python 
Python 2.7.12 (default, Jul 1 2016, 15:12:24) 
[GCC 5.4.0 20160609] on linux2 
Type "help", "copyright", "credits" or "license" for more information. 
>>> import whatever 
>>> help(whatever) 

Ausgabe lautet:

NAME 
    whatever - This is whatever help info. 

FILE 
    /home/el/whatever/__init__.py 

DESCRIPTION 
    This is whatever description 

    EXAMPLES: 
     ... 

PACKAGE CONTENTS 
    nothing (package) 
    something 

DATA 
    __version__ = '1.0' 
    variable = 'variable' 

VERSION 
    1.0 

Beispiele, die Sie im Beschreibungsteil angeben können. Also in ./whatever/__init__.py.

Hoffe, dass hilft.

Answer 2

Sieht aus wie die erste Zeile enthält eine kurze Beschreibung (sollte nicht eine Zeile überschreiten, wie in PEP 257 beschrieben), die nach dem Namen wird; gefolgt von einer Leerzeile und dann einem Absatz, was verwendet wird, um den Inhalt im Abschnitt BESCHREIBUNG bereitzustellen.

So zum Beispiel, wenn Sie dies in just_to_see/__init__.py (einfachem Beispiel mit einem Modul):

"""A short description 

A longer description on several lines etc. 
blablabla etc.""" 

def a_function(): 
    """ 
    An interesting introductive comment. 

    Some more explanations. 
    """ 
    pass 

(beachten Sie, dass der Doc-String an anderer Stelle sein kann, wie in einem __doc__ Attribute, wie here angegeben)

dann pydoc3.4 just_to_see/__init__.py AUSGABE:

Help on module __init__: 

NAME 
    __init__ - A short description 

DESCRIPTION 
    A longer description on several lines etc. 
    blablabla etc. 

FUNCTIONS 
    a_function() 
     An interesting introductive comment. 

     Some more explanations. 

FILE 
    /home/nico/temp/just_to_see/__init__.py 

Wenn sich Ihr Paket (in einem virtuellen environ installiert zum Beispiel), weitere Informationen finden Sie unter pydoc von setup.py (wie der Name des Autors usw.).

Ich bin mir nicht sicher, wie man einen BEISPIEL-Abschnitt auslöst. Konnte in der pydoc Ausgabe einer Standardpython-Bibliothek noch kein Beispiel für einen EXAMPLE-Abschnitt finden (aber ich habe sie nicht alle durchsucht). Vielleicht können Sie einen solchen Abschnitt in der langen Beschreibung in der Doc-Zeichenfolge Ihres Pakets hinzufügen. Aber da sie es in den Standardbibliotheken nicht zu tun scheinen, ist es vielleicht nicht der richtige Ort, um Beispiele zu geben.