pythondoc or epydoc?

[Christian Helmbold]

hi

I don't know which doctool I should use. At the moment gendoc is used in a
project, but as far as I know it isn't devoleped anymore. So I want to know
what you suggest: pythondoc, epydoc or something else? What is more
'offical'?

Thanks in advance.
Christian

 

[Thorsten Kampe]

* Christian Helmbold (2004-10-04 10:47 +0200)

I don't know which doctool I should use.

Use for what? This question is pretty senseless without a
specification what you want to do with it and what the doctool should
be able to do.

So I want to know what you suggest: pythondoc, epydoc or something
else? What is more 'offical'?

Nothing is "official" except "pydoc". The epydoc homepage has a pretty
informative overview:
http://epydoc.sourceforge.net/relatedprojects.html

I'd say switch to epydoc or happydoc (although I've haven't used
both).

Thorsten

 

[Colin J. Williams]

hi

I don't know which doctool I should use. At the moment gendoc is used in a
project, but as far as I know it isn't devoleped anymore. So I want to know
what you suggest: pythondoc, epydoc or something else? What is more
'offical'?

Thanks in advance.
Christian

I feel that epydoc makes a slighter better presentation than pydoc and
use the former.

Colin W.

 

[Remco Boerma]

So I want to know what you suggest: pythondoc, epydoc or something
else? What is more 'offical'?

Using epydoc (as i've used that one before) give's you the option to use
reStructuredText. With that, it's very easy to get some markup and
special meaning to your documentation. It's capable of javadoc like
syntax and reST. . . But be carefull though, as epydoc imports your
modules, so make sure every module you have that ought to do something
automagically uses something like:

if __name__ == "__main__":
	pass #code here

else, it will be run everytime you generate your code [i've had that
with a QUAD cleanup script- so everything was cleaned allright]

Cheers!
Remco Boerma

 

[Sean]

I would like to use epydoc to generate documents, but got the following error.

C:\PROJECT>\python23\python \python23\scripts\epydoc.py --debug test1.py
Importing 1 modules.
[1/1] Importing test1.py
Building API documentation for 1 modules.
[1/1] Building docs for test1
Building docs for test1
Building docs for test1.main
Building docs for test1.MyApp
Traceback (most recent call last):
File "\python23\scripts\epydoc.py", line 17, in ?
cli()
File "C:\Python23\lib\site-packages\epydoc\cli.py", line 110, in cli
docmap = _make_docmap(modules, options)
File "C:\Python23\lib\site-packages\epydoc\cli.py", line 483, in _make_docmap
try: d.add(module)
File "C:\Python23\lib\site-packages\epydoc\objdoc.py", line 2954, in add
self._add(objID)
File "C:\Python23\lib\site-packages\epydoc\objdoc.py", line 2968, in _add
self._add(link.target())
File "C:\Python23\lib\site-packages\epydoc\objdoc.py", line 2961, in _add
self.add_one(objID)
File "C:\Python23\lib\site-packages\epydoc\objdoc.py", line 2900, in add_one
self.data[objID] = ClassDoc(objID, self._verbosity)
File "C:\Python23\lib\site-packages\epydoc\objdoc.py", line 1589, in __init__
self._base_order = [make_uid(b) for b in base_order]
File "C:\Python23\lib\site-packages\epydoc\uid.py", line 781, in make_uid
uid = ObjectUID(object)
File "C:\Python23\lib\site-packages\epydoc\uid.py", line 418, in __init__
name = self._findname()
File "C:\Python23\lib\site-packages\epydoc\uid.py", line 509, in _findname
return '%s.%s' % (self.module(), objname)
File "C:\Python23\lib\site-packages\epydoc\uid.py", line 585, in module
if (self._module is not None and
File "C:\Python23\Lib\site-packages\wx\misc.py", line 3581, in __eq__
return _misc.DateTime___eq__(*args)
TypeError: Expected a pointer

The version of wxpython is 2.5.
This script can be executed normally.

How could I solve the problem?

Regards,
Sean

 

[David Keeney]

The biggest complaint I have about epydoc is that it presents all
inherited methods (and data attributes?) for each class, even those
inherited from the builtin 'object' class. There is a configuration
option to choose how those inherited elements are grouped, but none to
eliminate builtin attributes alltogether. Does anyone have a trick to
accomplish this, or is there a modified version of the epydoc script
around that produces builtin-less docs?

I figure programmers sophisticated enough to know what to do with the
inherited methods can divine the opportunity from the 'def
class(object):' line. For most readers, those inherited methods are
just clutter. The 'object' class is in many class defs because that
indicates 'new-style' to the python interpreter, rather than because
those inherited methods are specifically used or overridden.

David

 

[Amaury Forgeot d'Arc]

I would like to use epydoc to generate documents, but got the following error.
> ...
File "C:\Python23\lib\site-packages\epydoc\uid.py", line 585, in module
if (self._module is not None and
File "C:\Python23\Lib\site-packages\wx\misc.py", line 3581, in __eq__
return _misc.DateTime___eq__(*args)
TypeError: Expected a pointer
>
> The version of wxpython is 2.5.
> This script can be executed normally.

There is a bug in epydoc, corrected in CVS but not yet released:
http://cvs.sourceforge.net/viewcvs.py/epydoc/epydoc/src/epydoc/uid.py?rev=1.52&view=log

The commit description says:

> - Fixed bug in ObjectUID.module() (Using "x in lst" can fail if
> x.__eq__ raises an exception; use explicit "is" testing instead)

wxPython objects are wrapped C++ classes, and they don't support
comparison with arbitrary objects.

Try to apply the same diffs to your version of epydoc:
http://cvs.sourceforge.net/viewcvs.py/epydoc/epydoc/src/epydoc/uid.py?r1=1.51&r2=1.52
and this should correct the problem.

Amaury