Thanks for moving on this David, I'm still getting a machine set up to work on this, but I'm closer now. I like your doc attributes idea as it provides a very obvious way to access the extra docs via ipython, helper functions etc. Depending on how epydoc supports docs outside of the docstring, that may also be a good solution. I think we should avoid small examples in their own modules and reserve external modules for large, detailed examples a'la FiPy. If the 'dynamically accessing a wiki for docs' idea were implemented, it would have to be as an adjunct to completely self-contained documentation, so I'd keep it as an idea, but forget about implementing it now. I also think that docstrings should also have at least one minimal, typical-case call example. There's a compromise between bloat and help and I always find examples an enormous help. Gary R. David Huard wrote:
Gary,
I got epydoc running on plain docstrings and the latex-math role from Jens running. However, I havent't looked at how to use both together.
In any case, its not yet clear to me how the information should be organized. The first post on this thread suggested:
""" 1-2 sentences summarizing what the function does.
INPUT: var1 -- type, defaults, what it is var2 -- ... OUTPUT: description of output var or vars (if tuple)
EXAMPLES: a *bunch* of examples, often a whole page.
NOTES: misc other notes
ALGORITHM: notes about the implementation or algorithm, if applicable
AUTHORS: -- name (date): notes about what was done """
But I think this is maybe too heavy for doctrings. Anyone using IDLE will see large yellow docs pop up. I think docstrings should limit themselves to:
""" 1-2 sentences summarizing what the function does.
INPUT: var1 -- type, defaults, what it is var2 -- ... OUTPUT: description of output var or vars (if tuple)
SEE ALSO: """
The question now is: where too put all the other stuff, namely the examples, notes, algorithm and authorship. Unless I'm mistaken, epydoc has support for documentation outside of the docstring, so we could use that. Another idea is to assign "documentation attributes" to functions. For instance:
def func(a,b,c): """definition :Input: ... :Output: ... :See also: ... """ func.__examples__=[ """ >>> func(1,2,3) [4,5,6] ... """, """...""", ...] func.__author__='Bobby' func.__notes__=' Those attributes could be accessed by an example function def example(function, i=None): """Run example i from function. If i is None, run all examples. """ and eventually an ipython magic command (func?!).
The other solution is to put the examples in completely different files, or fetch them from a wiki page (but I don't think this is implemented yet in epydoc).
I think we should dig more into what epydoc offers before rushing into this. Then we could propose a couple of different layouts, and once everyone agrees on which is best, go ahead and apply it at large.
I started looking at FiPY's documentation and their setup is impressive. I'll look more deeply into it.
David