missing - python 3 docstring example

¿Cómo creo documentación con Pydoc?

Question

Estoy tratando de crear un documento de mi módulo. Utilicé pydoc desde la línea de comandos en Windows 7 usando Python 3.2.3:

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

Esto llevó a que mi shell fuera rellenado con texto, una línea para cada archivo en mi módulo, diciendo:

no Python documentation found for ''<file_name>''

Es como si Pydoc intentara obtener documentación para mis archivos, pero quiero crearla automáticamente. No pude encontrar un buen tutorial usando Google. ¿Alguien tiene algún consejo sobre cómo usar Pydoc?

Si intento crear documentación a partir de un archivo usando

python ... -w myModule/myFile.py, it says "wrote myFile.html", and when I open it, it has one line of text saying:

# ../myModule/myFile.py

Además, tiene un enlace al archivo en mi computadora, en el que puedo hacer clic y muestra qué hay dentro del archivo en mi navegador web.

Answer 1

Como RocketDonkey sugirió, su módulo sí mismo necesita tener algunas docstrings.

Por ejemplo, en myModule/__init__.py :

"""
The mod module
"""

También querrá generar documentación para cada archivo en myModule/*.py usando

pydoc myModule.thefilename

para asegurarse de que los archivos generados coinciden con los que se hace referencia desde el archivo de documentación del módulo principal.

Answer 2

Otra cosa que la gente puede encontrarle útil ... asegúrese de dejar ".py" del nombre de su módulo. Por ejemplo, si intenta generar documentación para ''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 3

pydoc es fantástico para generar documentación, pero la documentación debe escribirse en primer lugar. Debe tener cadenas de texto en su código fuente como fue mencionado por RocketDonkey en los comentarios:

"""
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 primera docstring proporciona instrucciones para crear la documentación con pydoc. Hay ejemplos de diferentes tipos de documentos para que pueda ver cómo se ven cuando se generan con pydoc.

Answer 4

use pydoc.doc () puede mostrar docstring, puede ser clase, módulo, etc.