97

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.

Improve this question
3
  • 2
    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? Commented Oct 24, 2012 at 0:26
  • 2
    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? Commented Oct 24, 2012 at 0: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. Commented Nov 17, 2020 at 17:32

5 Answers 5

Reset to default
119

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
Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

I wonder why the accepted answer not provide this tiny little detail! WIthout dropping .py, it won't work atleast in Py3.
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: Actually, as long as the directory containing the module is in sys.path, pydoc will be able to find it.
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
90

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.

Improve this answer

Comments

39

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.

Improve this answer

1 Comment

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

works on windows7:

python -m pydoc -w my_module
Improve this answer

Comments

0

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/

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.