[Doc-SIG] "inverse" documentation generation
Vicki Brown
vlb at ironport.com
Thu May 12 19:56:33 CEST 2005
And now for something (perhaps) completely diifferent.
Most "documentation generators" are optimized for someone working
_on_ the code rather than _with_ the code. That is, they work from
the assumption that you have a method/class/module and want to know
how it works - not from the view that you know what you want to do
and want to discover the best method/class/module that will let you
accomplish your goal in the least amount of time and effort :)
I want to be able to generate documentation that aids a client in
using a set of Python modules, not in implementing and maintaining
those modules.
Example:
Bob is using an automated test framework written in Python. He's
writing a test and he'd like to call a routine that will "be like
hitting return over and over until it gets me back out to the top of
my test." He asks John (one of the framework authors) who says:
"We've got that; it's called restart".
Bob then hunts through the pydoc documentation for the 100
modules and packages in the framework, then resorts to a find command
on the source tree (searching for for "def restart"), and eventually
discovers 5 different "restart" methods scattered throughout the
code. Back in pydooc, he sees that one of these has a docstring that
looks like "the right one".
"""
restart():
Resets the session to a base state, ready for more method calls.
"""
The rest appear to be internal methods, not API at all.
If John wasn't available, how would Bob ever discover this
method? He doesn't know its name. He doesn't know which class or
module it's in. He doesn't want to read through pages of pydoc HTML
files or familiarize himself with the entire framework code base. He
wants to _write a test_.
Even if he started with a"find" on the source tree (or a search
through the HTML-ized docs), he may not pick the right keywords for
the search.
I need a way to enhance Bob's efficiency as a client of the
framework, not a developer of the framework.
At the very least, I think what I want is a way to extract the
method, class, and module names, and their docstrings, and present
them in an inverse presentation format: instead of digging down
through module to class to method, I want to start from the
docstrings. I want to start from the viewpoint of "I know what I want
to do. Now tell me how to do it".
Comments, suggestions, ideas, and general discussion welcomed.
--
- V.
Vicki Brown <vlb at ironport.com> * Internal Technical Documentation
http://home.ironport.com/~vlbrown * Jabber: vlbrown at ironport.com
* Words are, of course, the most powerful drug used by mankind. *
-- Rudyard Kipling
More information about the Doc-SIG
mailing list