[SciPy-dev] Fledgling livedocs website

[Arnd Baecker]

Hi,

On Sat, 6 Nov 2004, Travis Oliphant wrote:

> For those who wish to have input, here is my start on the livedocs site
> for SciPy.
>
> Right now, a dynamically-built tree showing the scipy docs for most
> objects in scipy is available.
>
> Go to http://oliphant.ee.byu.edu:81
>
> (soon this should be an alias for http://www.scipy.org/livedocs/ )

This is really nice and very helpful!

> At some point, I'd like this site to be editable with changes being
> committed back to the scipy source.   But, for now, it does serve as a
> nice hierarchial reference page.

This deserves an announcement on scipy-user, IMHO.
(Though I am wondering if one should wait until editing
was possible  -  one might then be able to gain the full momentum
of people looking at their most beloved subject and
adding comments straight away ;-)

Concerning making the site editable:
I think that there will be two types of changes:
  a) corrections and small additions to the doc-string
  b) usage example, code snippets (and maybe more).

Is your plan to put b) under the heading "Extra Information" ?
(and in the end

You wrote that "most objects in scipy", so you are
presumably aware of links like

http://oliphant.ee.byu.edu:81/scipy/xplt/plot
http://oliphant.ee.byu.edu:81/scipy/special/j0

giving "Sorry, but I couldn't find the object you requested".
This looks like either 'functions' (plot),
'builtin_function_or_method' (plg) or
'ufunc's (j0).
Interestingly, in the first cases doc-string exists,
  print scipy.xplt.plg.__doc__
whereas for ufuncs I have no idea how to access that
properly (Fernando will know that becaue
In [17]: scipy.special.j0?
works.
((For that type of functions option a) for changes
will not be possible, I presume))

How tricky would it be to support these objects as well?

How do you extract all the information? Do you use
a script to pre-extract all doc-string in a recursive way?
(And how did you get the links to the sub-modules done?)
I am just curious - it looks really nice!!
Is there a way to download the full tree of documentation
or is everything created dynamically?
(I am thinking of adding the full tree as a "book" to documancer ...;-)

BTW: yesterday I tried epydoc on scipy - it
seems to work reasonably well (though it seg-faulted close
to the end).
At least when fed to documancer it helps finding routines.
However, overall the result of epydoc is pretty
confusing (for example look at the output for xplt it
shows all the underlying gist routines, weird variables
and other stuff which seems pretty useless, especially for
beginners ....)
The result you obtain seems much clearer and more useful
to me!



Arnd