[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