Plone is a modular CMS, which can be expanded with additional products. That means new features are easy to install, and also to customize. However, quickly understanding code that other people wrote, might turn tricky as there are as each coder uses his own style. Therefore, it might be useful to get an overall picture of the system before diving into details.
Documentation generators are useful for giving a comprehensive view on code. These are applications that traverse through code and extract information out of it. They use the structured information then to produce a nice looking reference of the code. Ever heard about API? Yep. Ever seen that sort of documentation among any 3rd party Plone product? At least I haven’t.
Luckily, there a few choices suitable for Plone/Python:
Parsers: doxygen (generic), epydoc (defines ‘epytext’, parses also others), docutils (defines and parses ‘reStructuredText’) Extensions: graphviz (builds visualization graphs) Plugins: eclox (an Eclipse plugin that uses doxygen, which uses graphviz)
(Plone API’s at api.plone.org use epydoc btw.)
Out of these, I quickly tested doxygen on a Plone product called EasyShop. The result was interesting but without use. EasyShop does only little subclassing and therefore the documentation doxygen produced was basically listings of separate classes and methods. Doxygen uses graphviz to build graphical visualizations of class relations, but those were out of use also. The problem here is that Plone products are not common python packages: they have adapters, utilities, views, events, subscribers and such. Creating dececnt API out of these would need a specific solution targeted at the platform.
Documentation generating seems interesting, however, and graphviz the most providing out of the whole bunch. Unfortunately, I couldn’t produce anything useful on my first few tries, but the subject just needs a little more research. After all, think about it: an API-like documentation with UML-like graphs of any Plone product, wouldn’t that be nice?
It’s not clear to my from your blog post if you’re aware of DocFinder and DocFinderTab, which generate at runtime the docstrings, through introspection of live objects.
Another approach: generate end-user documentation from the code. Example: the tagged value and stereotype lists of archgenxml on plone.org. I modified the archgenxml code so that it itself could generate those lists: code and documentation are in sync.
Also in instancemanager, some end-user documentation is generated.
Both are not the types of generated documentation you talk about in your article, but worthy of a mention, too 🙂
Reinout
You might want to take a look at pydoctor as well
http://codespeak.net/~mwh/pydoctor
https://launchpad.net/pydoctor
It has at least some support for Zope’s interfaces.
Raphael
Nice to see replies to my very first post 🙂
DocFinder(Tab) is useful extension but provides overview to only objects themselves and for only one at a time. It doesn’t explain how code functions and how things relate to each other.
I haven’t actually used ArchGenXML yet, but I took a look at the stereotype and tagged value references that Reinout van Rees mentioned. The lists are something I would like to see for every plone product, not to mention the plone bundle itself. Oh yes, Plone actualy _has_ API, but for comparison, take a look at ruby API at http://api.rubyonrails.org/ and http://api.plone.org Which one do you think actually helps a developer?
PyDoctor seems nice, but it lacks visualization, relation maps etc (it only produces listings of modules, methods, classes etc.). Support for Zope interfaces sure is a step forward, however. Still, we are far away from where we could be (reverse-UML that might be).