[SciPy-dev] Fwd: [sage-devel] numpy in SAGE, etc.

[Gary Ruben]

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