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

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

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

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

no Python documentation found for '<file_name>'

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

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

python ... -w myModule\myFile.py

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

# ../myModule/myFile.py

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


python-3.x python documentation documentation-generation pydoc
person Community    schedule 23.10.2012    source источник
comment
pydoc -w moduleName у меня работает для одного модуля с одной функцией. Можете ли вы попытаться создать простой пример, который будет воспроизводить это? Структура каталога и содержимое файлов, и где вы запускаете какую команду?   -  person millimoose    schedule 24.10.2012
comment
Заранее извиняюсь, если это глупый вопрос, но есть ли у вас docstrings/etc. в вашем модуле? Это означает, что у вас есть контент в исходном файле, который должен создать запуск pydoc?   -  person RocketDonkey    schedule 24.10.2012
comment
Для тех, кто попадает на эту страницу после быстрого поискового запроса о том, как автоматически генерировать документацию в .py файлах. pydoc не для этого. Pydoc предназначен для тех случаев, когда вы уже написали эту документацию и хотите сделать ее красивой.   -  person a.t.    schedule 17.11.2020

Ответы (3)


arrow_upward
37
arrow_downward

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

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

"""
The mod module
"""

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

pydoc myModule.thefilename

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

person michel-slm    schedule 24.10.2012
comment
... И когда у вас есть строки документации, рассмотрите возможность использования pdoc, потому что он дает результат, который ближе к тому, что ожидается от документации API сегодня. - person K3---rnc; 11.01.2019

arrow_upward
101
arrow_downward

Еще одна вещь, которая может оказаться полезной... не забудьте убрать ".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
person K.S.    schedule 11.01.2015
comment
Интересно, почему принятый ответ не содержит этой крошечной детали! Без удаления .py он не будет работать по крайней мере в Py3. - person ThinkCode; 04.03.2016
comment
Это помогло. Я также обнаружил, что при выполнении pydoc нам нужно находиться в одном и том же каталоге... т. е. мы не можем выполнить pydoc dir/prg.py. Нам нужно cd dir, а затем сделать pydoc prg.py. Это правильно? - person abhijithda; 06.04.2016
comment
@abhijithda: На самом деле, пока каталог, содержащий модуль, находится в sys.path, pydoc сможет его найти. - person Tom Barron; 04.12.2016
comment
Это был самый полезный способ сделать это, я знаю, что это закрыто, но, по крайней мере, в python 2.7 теперь я могу выполнить python -m pydoc Example_Pydoc (без .py) и получить свою документацию. Спасибо - person Taku_; 26.01.2018

arrow_upward
83
arrow_downward

pydoc отлично подходит для создания документации, но документация должна быть написана в первую очередь. У вас должны быть строки документации в исходном коде, как было упомянуто 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")

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

person zzzirk    schedule 24.10.2012