The most powerful of the python CodeDocumentationTools. This can be persuaded to work for Zope code, but it's not easy.
- API documentation
- links to some examples of epydoc applied to Zope code
- http://epydoc.sourceforge.net
- epydoc home
- http://mail.python.org/pipermail/doc-sig/2002-October/002815.html
- comparison with pydoc
- http://cvs.sourceforge.net/viewcvs.py/plone-docs/Developers/Tools/epydoc
- version in plone-doc CVS - may have some fixes for zope
- http://mail.zope.org/pipermail/zope-dev/2003-March/019216.html
- Dieter's pydoc patches, useful ?
Examples
Installation on debian:
$ sudo feta install python-epydoc Running: apt-get install python-epydoc Reading Package Lists... Done Building Dependency Tree... Done python-epydoc is already the newest version. 0 upgraded, 0 newly installed, 0 to remove and 185 not upgraded.
Running it on Zwiki:
$ cd /zope1/Products /zope1/Products$ PYTHONPATH=/zope1:/zope/lib/python epydoc -o /var/www/zopewiki.org/epydoc ZWiki Error: 'ZWiki' is not a pacakge Importing 1 modules. [.] Building API documentation for 1 modules. [.] Writing HTML docs (10 files) to '/var/www/zopewiki.org/epydoc'. [..........] /zope1/Products$
Generated some things. Why is not a pacakge ?
Running it on Plone:
$ cd /zope1/Products /zope1/Products$ PYTHONPATH=/zope1:/zope/lib/python epydoc -o /var/www/zopewiki.org/epydoc CMFPlone Importing 100 modules. [ 1%] .. Error importing 'CMFPlone.ActionIconsTool': No module named CMFActionIcons.ActionIconsTool . Error importing 'CMFPlone.ActionsTool': No module named CMFCore.ActionsTool . Error importing 'CMFPlone.CalendarTool': No module named CMFCalendar.CalendarTool . (etc...) Error importing 'CMFPlone.tests.zcheck': No module named CMFPlone.tests . Building API documentation for 26 modules. [..........................] Writing HTML docs (79 files) to '/var/www/zopewiki.org/epydoc'. [ 1%] ............................................................ [ 77%] ................... /zope1/Products$
Import errors, but again it generated something.
Running it on all zope source
We are trying to get this working, see below.
a fix -- Sat, 17 Apr 2004 14:51:35 -0700 reply
Maik says to check Developers section of plone-book CVS for a fix..
tips from plone-users --simon, Wed, 05 May 2004 21:42:14 -0700 reply
:
Some pointers:
- use Epydoc 2.1: it has ExtensionClass support
- use Zope HEAD: Epydoc works better with the new ExtensionClass
- add Zope's lib/python to sys.path
E.g., this script called from the root of a Zope HEAD instance creates a (more than) complete CMF API documentation in doc/cmf-api:
PYTHONPATH="lib/python"
export PYTHONPATH
epydoc --docformat restructuredtext \
--target doc/cmf-api \
Products/CMFCore \
Products/CMFTopic \
Products/CMFDefault \
Products/CMFCalendar \
Products/DCWorkflow \
Products/CMFActionIcons
The result is not perfect, but is very helpful to understand the complex inheritance trees of Zope 2. Using it with Plone will give you even more impressive inheritance trees
Cheers,
Yuppie
BTW: Epydoc has no support for Zope Interfaces. See this link for an attempt to use it with Interfaces:
http://cvs.sourceforge.net/viewcvs.py/plone/CMFPlone/interfaces/Attic/README-interfaces.txt?rev=1.1.2.2&view=markup
latest -- Wed, 16 Jun 2004 11:56:08 -0700 reply
Using zope 2.7.1b2, python 2.3.4, epydoc 2.1 with the attached patch. It randomizes UIDs? in the event that a module has no name, preventing clashes. It also deals with bad filenames which appear to occur in ZClass?.
sm: if I run it over any substantial amount of source, it goes nuts with uid errors then segfaults
tagalog: sm: it did that for me, then I rm'ed all the tests and now it works
... -- Wed, 16 Jun 2004 15:54:49 -0700 reply
:
ok, check out http://... -- doc/ has the results, epy-zope.patch is the patch against epydoc 2.1, generate.sh is my command line
Nice. I can't reproduce your success on this server.. maybe tomorrow.
tagalog says: I've found that epydoc is not very chatty about import errors. if something can't be imported, chances are, it won't complain.
latest -- Fri, 18 Jun 2004 13:33:49 -0700 reply
AccessControl?/tests makes it segfault. After patching epydoc to skip all tests directories, I get this far:
$ PYTHONPATH=/zope/lib/python epydoc -o /var/www/zopewiki.org/ep\ydoc /zope/lib/python/* Importing 958 modules. [ 0%] ......................................................... <snip> Error importing 'nt_svcutils.service': No module named win32serviceutil ........ Error importing '/zope/lib/python/version.txt': not a Python module ................................
Here it hangs doing nothing much.
How to use epydoc with Zope 2.7 --d2m, Sun, 19 Sep 2004 21:56:12 -0700 reply
http://zope.org/Members/lunatik/HowTo.2004-06-02.4509
... but note the final comment --slinkp, Thu, 09 Jun 2005 09:29:18 -0700 reply
I added a comment that 90% of that HowTo? script is unnecessary, since it
zopectl already does all that. For generating Product documentation, this works pretty well for me.
... but note the final comment --d2m, Thu, 09 Jun 2005 10:12:03 -0700 reply
this is great - you should add that comment to this wiki page too