Documenting a package with Pydoc

[Rob Cowie]

I have searched this group and the wider net to find an answer to this,
but I haven't been successful.

Pydoc seems to be capable of writing documentation for all modules
within a package by simply pointing it to the package on the command
line...

pydoc -w <packagename_without_/>

Certainly, the method writedocs() appears to descend into a directory
and create docs for each importable object.

Perhaps I'm doing something wrong but when I do this, pydoc reports
that no Python documentation can be found for each of the contents of
the package. Of course, if I point pydoc directly to the modules, it
succeeds.

Am I doing something wrong?

Cheers, Rob C

[Rob Cowie]

Anyone?

[Gabriel Genellina]

At Friday 18/8/2006 11:45, Rob Cowie wrote:

>Pydoc seems to be capable of writing documentation for all modules
within a package by simply pointing it to the package on the command
line...

pydoc -w <packagename_without_/>

Certainly, the method writedocs() appears to descend into a directory
and create docs for each importable object.

Perhaps I'm doing something wrong but when I do this, pydoc reports
that no Python documentation can be found for each of the contents of
the package. Of course, if I point pydoc directly to the modules, it
succeeds.

Am I doing something wrong?

That appears to be a bug. In pydoc.writedocs, when iterating over the
package directory contents, it uses inspect.getmodulename(path). That
returns the bare filename (without path nor extension) (is it ok???),
and later the resolve() function can't load the module because it
lacks package information.

For simple cases this patch may work: In writedocs, add the following
line at the beginning:
if pkgpath=='' and ispackage(dir): pkgpath = os.path.basename(dir) + '.'

This works for top level packages located at sys.path, but not for
packages located elsewhere.

By example, I can generate now the docs for pychart:

python c:\apps\python\lib\pydoc.py -w c:\apps\python\lib\site-packages\pychart

Gabriel Genellina
Softlab SRL

__________________________________________________
Preguntá. Respondé. Descubrí.
Todo lo que querías saber, y lo que ni imaginabas,
está en Yahoo! Respuestas (Beta).
¡Probalo ya!
http://www.yahoo.com.ar/respuestas

[Rob Cowie]

Gabriel Genellina wrote:

At Friday 18/8/2006 11:45, Rob Cowie wrote:

Pydoc seems to be capable of writing documentation for all modules
within a package by simply pointing it to the package on the command
line...

pydoc -w <packagename_without_/>

Certainly, the method writedocs() appears to descend into a directory
and create docs for each importable object.

Perhaps I'm doing something wrong but when I do this, pydoc reports
that no Python documentation can be found for each of the contents of
the package. Of course, if I point pydoc directly to the modules, it
succeeds.

Am I doing something wrong?

That appears to be a bug. In pydoc.writedocs, when iterating over the
package directory contents, it uses inspect.getmodulename(path). That
returns the bare filename (without path nor extension) (is it ok???),
and later the resolve() function can't load the module because it
lacks package information.

I don't think this is a bug; inspect.getmodulename(path) does indeed
return a bare filename, but this is later augmented with the pkgpath.

I also can't find a resolve() function. Perhaps we have different
versions? I have revision 1.38.

For simple cases this patch may work: In writedocs, add the following
line at the beginning:
if pkgpath=='' and ispackage(dir): pkgpath = os.path.basename(dir) + '.'

This works for top level packages located at sys.path, but not for
packages located elsewhere.

By example, I can generate now the docs for pychart:

python c:\apps\python\lib\pydoc.py -w c:\apps\python\lib\site-packages\pychart

Gabriel Genellina
Softlab SRL

Thanks,

Rob C

>
__________________________________________________
Preguntá. Respondé. Descubrí.
Todo lo que querías saber, y lo que ni imaginabas,
está en Yahoo! Respuestas (Beta).
¡Probalo ya!
http://www.yahoo.com.ar/respuestas