Я пытаюсь создать документ из моего модуля. Я использовал 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
Кроме того, он имеет ссылку на сам файл на моем компьютере, по которому я могу щелкнуть, и он показывает, что находится внутри файла в моем веб-браузере.
Как предложил RocketDonkey, ваш модуль должен иметь некоторые docstrings.
Например, в myModule/__init__.py:
"""
The mod module
"""
Вы также хотите создать документацию для каждого файла в myModule/*.py, используя
pydoc myModule.thefilename
чтобы убедиться, что сгенерированные файлы соответствуют тем, которые указаны в файле документации основного модуля.
Другое дело, что люди могут найти полезные... не забудьте оставить ".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
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.
use pydoc.doc() может показывать docstring, может быть классом, модулем и т.д.