pythondocumentationpydoc

How to generate documentation using Pydoc

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

Solution

  • 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.