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
2006/12/16, Gary Ruben <
gruben@bigpond.net.au>:In case I gave the impression I was planning to do something on this, I
still am. It's just that I've been very busy. I am still planning to try
to build the FiPy docs and then spin a skeleton document based on it for
numpy, perhaps with content from the numarray docs, and another for
scipy during the upcoming Christmas break.
Each of these docs would have one appendix which contains a reference
built from the individual method/function docstrings. Each would also
have another appendix of long full-module examples with LaTeX and
plotting results. I was also going to try to write a docstring
documentation spec as part of this.
This is quite a bit of work for me as I expect I need a few days
preparation to get a Linux distro up to date with a build system. I
thought the concensus was headed toward epydoc + ReST with LaTeX markup,
so I was planning to adopt FiPy's nice model for using this. I still
hadn't ruled out doxygen and I was planning on looking at it too to see
if it has advantages. My guess is that either would be fine, although
people here might be more comfortable with epydoc.
David, if this sounds like a good plan to you, perhaps you can move
ahead with this, as it'll be a few days before I can start.
Gary R.
David Huard wrote:
> Hi all,
>
> I followed this thread with much interest and I wouldn't like it to die
> without some kind of concensus being reached for the Scipy documention
> system. Am I correct to say that Epydoc + REST/Latex seems the way to go ?
>
> If this is the case, what's next ? I'm not familiar with any of this,
> but I'd be great if someone knowledgeable could define a roadmap and
> create a couple of tickets so that people like me could contribute small
> steps.
>
> Cheers,
>
> David
_______________________________________________
Scipy-dev mailing list
Scipy-dev@scipy.org
http://projects.scipy.org/mailman/listinfo/scipy-dev