Как создать документацию с помощью Pydoc?

Я пытаюсь создать документ из моего модуля. Я использовал pydoc из командной строки в Windows 7, используя Python 3.2.3:

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

Это привело к тому, что моя оболочка была заполнена текстом, по одной строке для каждого файла в моем модуле, говоря:

no Python documentation found for '<file_name>'

Это как будто Пидок пытается получить документацию для моих файлов, но я хочу создать ее автоматически. Я не смог найти хороший учебник с помощью Google. У кого-нибудь есть какие-либо советы по использованию Pydoc?

Если я пытаюсь создать документацию из одного файла, используя

python ... -w myModule\myFile.py

там написано wrote myFile.html, и когда я его открываю, в нем есть одна строка текста:

# ../myModule/myFile.py

Кроме того, он имеет ссылку на сам файл на моем компьютере, по которому я могу щелкнуть, и он показывает, что находится внутри файла в моем веб-браузере.

Ответ 1

Как предложил RocketDonkey, ваш модуль должен иметь некоторые docstrings.

Например, в myModule/__init__.py:

"""
The mod module
"""

Вы также хотите создать документацию для каждого файла в myModule/*.py, используя

pydoc myModule.thefilename

чтобы убедиться, что сгенерированные файлы соответствуют тем, которые указаны в файле документации основного модуля.

Ответ 2

Другое дело, что люди могут найти полезные... не забудьте оставить ".py" из вашего имени модуля. Например, если вы пытаетесь создать документацию для 'original' в ' original.py':

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

yourcode_dir$ pydoc -w original
wrote original.html

Ответ 3

pydoc фантастичен для создания документации, но документация должна быть написана в первую очередь. У вас должны быть docstrings в исходном коде, как упоминалось RocketDonkey в комментариях:

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

Первая docstring содержит инструкции по созданию документации с pydoc. Существуют примеры различных типов докстрон, чтобы вы могли видеть, как они выглядят, когда сгенерированы с помощью pydoc.

Ответ 4

use pydoc.doc() может показывать docstring, может быть классом, модулем и т.д.