How to generate documentation using Pydoc

问题

I need to generate documentation from comments using pydoc. What are the basic steps to do that?

回答1:

If you really want to use Pydoc, you can simply do in a terminal:

$ pydoc -w myproject

This will generate an old-school HTML documentation from doctrings. Note that Pydoc is the module used in Python since 2.1 for the help() function. It will retrieve the docstrings which are NOT comments. You should describe your functions using docstrings.

But it is a kind of old-school using Pydoc for documentation generating. The popular tool to do that in Python is Sphinx. But you'll need to format your docstrings in a particular format as reStructuredText.

You could also use pdoc, which auto-extracts documentation from your docstrings (i.e. public API) and supports markdown, numpydoc, google-style docstrings format and some reStructuredText directives.

Have a look here to get some information concerning docstrings formatting.

You can also use Pyment to generate docstring skeletons or convert existing ones to a particular format.

回答2:

Alternatively, if you want a simple text file instead of HTML, you can redirect the console output to a file with this simple command:

$ pydoc myproject > helpfile.txt

This file can be printed or uploaded to Github without too much additional effort.

来源：https://stackoverflow.com/questions/26587763/how-to-generate-documentation-using-pydoc