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.

`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? — millimoose, Oct 24 '12 at 00:26
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? — RocketDonkey, Oct 24 '12 at 00:40
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. — a.t., Nov 17 '20 at 17:32

score 113 · Answer 1 · answered Jan 11 '15 at 18:36

113

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

answered Jan 11 '15 at 18:36

K.S.

2,846
4
24
32

6

I wonder why the accepted answer not provide this tiny little detail! WIthout dropping .py, it won't work atleast in Py3. – ThinkCode Mar 04 '16 at 17:54
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? – abhijithda Apr 06 '16 at 20:40
@abhijithda: Actually, as long as the directory containing the module is in sys.path, pydoc will be able to find it. – Tom Barron Dec 04 '16 at 15:13
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 – Taku_ Jan 26 '18 at 14:55

score 88 · Answer 2 · edited Sep 09 '16 at 17:32

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.

score 38 · Accepted Answer · edited Apr 20 '16 at 21:20

38

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.

edited Apr 20 '16 at 21:20

the Tin Man

158,662
42
215
303

answered Oct 24 '12 at 06:04

michel-slm

9,438
3
32
31

2

... And once you have [docstrings](https://docs.python.org/3/glossary.html#term-docstring) in place, consider using [pdoc](https://pdoc3.github.io/pdoc) instead, because it produces a result that is closer to what is expected of API documentation today. – K3---rnc Jan 10 '19 at 21:27

score 0 · Answer 4 · answered Apr 12 '22 at 12:13

0

works on windows7:

python -m pydoc -w my_module

answered Apr 12 '22 at 12:13

Marcel Suleiman

106
4

How do I create documentation with Pydoc?

4 Answers4

Linked