On 9/21/07, Jason Grout <[EMAIL PROTECTED]> wrote:
>
> William Stein wrote:
>
> > Incidentally, the whole sage documentation structure started from
> > the Python documentation (probably Python 2.4), which I just
> > motivated to be the Sage manuals instead. I had experimented
> > a lot with automated tools like epydoc, etc., and found that they
> > break a lot on the incredibly complicated Sage library, they don't
> > play well with Cython code (which is nearly 1/3rd of Sage?), and
> > and they just don't feel as well organized and readable as something
> > that a person has to spend time putting together. The current
> > documentation -- though not comprehensive -- tends to only
> > have things in it that are "reasonably usable and stable", so the
> > stuff that epydoc would pick up that is really a mess isn't there.
> >
> > That said, *pydoc has probably improved a lot in the last 2 years
> > (since I last used it), and it would be good to have some 100%
> > complete autogenerated variant of the reference manual in
> > addition to the current more manually organized one.
>
> Is one requirement for any such system the ability to deal with math in
> the documentation?
That would be nice and is a big advantage of the current latex system.
That said, something autogenerated with ugly math in it (not typeset)
would be useful, probably.
> After browsing for a little bit, it seems like that
> is a sticky point that many systems don't address, other than pydoc,
> though epydoc does have some sort of construct for math ( X{x+y} ).
> It's nice now to have the documentation in latex so that we can write a
> mathematical explanation.
No matter what, the input in doctests will be latex notation. I'm definitely
not going to consider using some funky math notation for the documentation.
William
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://sage.scipy.org/sage/ and http://modular.math.washington.edu/sage/
-~----------~----~----~----~------~----~------~--~---
