How do I create documentation with Pydoc?

Question

I'm trying to create a document out of my module. I used pydoc from the command-line in Windows 7 using Python 3.2.3:

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

This led to my shell being filled with text, one line for each file in my module, saying:

no Python documentation found for '<file_name>'

It's as if Pydoc's trying to get documentation for my files, but I want to autocreate it. I couldn't find a good tutorial using Google. Does anyone have any tips on how to use Pydoc?

If I try to create documentation from one file using

python ... -w myModule\myFile.py

it says wrote myFile.html, and when I open it, it has one line of text saying:

# ../myModule/myFile.py

Also, it has a link to the file itself on my computer, which I can click and it shows what's inside the file on my web browser.

Robi

pydoc -w moduleName works for me for a single module with one function in it. Can you try to create a simple example that would reproduce this? A directory layout and the contents of the files, and where you're running which command? – Rouge

Apologies in advance if this is a stupid question, but do you have docstrings/etc. in your module? Meaning do you have the content in your source file that running pydoc should produce? – Skerl

For those reaching this page after a quick search query on how to auto-generate documentation in .py files. That is not what pydoc is for. Pydoc is for when you already wrote that documentation, and want to make it pretty. – Writeup

Answer 1

As RocketDonkey suggested, your module itself needs to have some docstrings.

For example, in myModule/__init__.py:

"""
The mod module
"""

You'd also want to generate documentation for each file in myModule/*.py using

pydoc myModule.thefilename

to make sure the generated files match the ones that are referenced from the main module documentation file.

Horvitz

... And once you have docstrings in place, consider using pdoc instead, because it produces a result that is closer to what is expected of API documentation today. – Feigned

Answer 2

Another thing that people may find useful...make sure to leave off ".py" from your module name. For example, if you are trying to generate documentation for 'original' in 'original.py':

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

yourcode_dir$ pydoc -w original
wrote original.html

Monteverdi

I wonder why the accepted answer not provide this tiny little detail! WIthout dropping .py, it won't work atleast in Py3. – Disjunctive

This helped. I also found that, when executing the pydoc, we need to be in the same directory... i.e., we can't do pydoc dir/prg.py. We need to cd dir and then do pydoc prg.py. Is that right? – Parapodium

@abhijithda: Actually, as long as the directory containing the module is in sys.path, pydoc will be able to find it. – Supen

This was the most helpful way to do this, I know this is closed but at least in python 2.7 I can now do python -m pydoc Example_Pydoc (without the .py) and get my documentation . Thank you – Sweetscented

Answer 3

pydoc is fantastic for generating documentation, but the documentation has to be written in the first place. You must have docstrings in your source code as was mentioned by RocketDonkey in the comments:

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

The first docstring provides instructions for creating the documentation with pydoc. There are examples of different types of docstrings so you can see how they look when generated with pydoc.

Read

Answer 4

works on windows7:

python -m pydoc -w my_module

Gibeonite

Answer 5

PyDoc reads and generates documentation based on the docstrings you have written in your code. Docstrings are just comments enclosed in triple quotes that tell others what the code does, what the parameters are or what the function returns. I suggest two ways to do that:

One way to generate an HTML documentation from inside your code editor, is to just import pydoc and at the end use pydoc.writedoc('name_of_my_module') . This generates name_of_my_module.html in the same directory.

import pydoc

def add(x, y):
"""
    Params:
      x and b are numbers (int or float)
    Returns: 
      the sum of x and y.
"""
    return x + y

pydoc.writedoc('my_module')

Alternatively, you can remove the import pydoc and the last line and instead use command line by using python -m pydoc -w my_module

To learn more you can read the following article: https://pythonology.eu/how-to-use-pydoc-to-generate-documentation-in-python/

Juliusjullundur