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

[David Huard]

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 at 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 at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20061218/85ba1c5d/attachment.html>