[SciPy-dev] Fledgling livedocs website
oliphant at ee.byu.edu
Sat Nov 6 23:09:47 CST 2004
Arnd Baecker wrote:
>On Sat, 6 Nov 2004, Travis Oliphant wrote:
>>For those who wish to have input, here is my start on the livedocs site
>>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
Yes, the easiest thing to do right now would be to place this extra
stuff in comments right before the source code until something else is
worked out (right now that is what extra information is grabbing using
>You wrote that "most objects in scipy", so you are
>presumably aware of links like
Thanks for pointing these out. They actually should be working. I'm
not sure why they are not...
>giving "Sorry, but I couldn't find the object you requested".
>This looks like either 'functions' (plot),
>'builtin_function_or_method' (plg) or
>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 : scipy.special.j0?
>((For that type of functions option a) for changes
>will not be possible, I presume))
Editing the docstrings for builtin functions or ufuncs will be tricky as
these are int c-code. Displaying them is fine.
>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 ...;-)
This is all dynamically generated from the docstrings. There is some
special interpretation given to module docstrings that describe their
functions to put the links in. But, pretty much when an object is
looked for the web-server has an active scipy installation available to
get docstrings from. Thank twisted python and nevow (a python web
framework) for the dynamicism. They didn't take too long to learn the
basics, but I'm still quite a neophyte (witness the missing functions
>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
Yes, just having a hierarchial documentation set built from docstrings
should be useful. Most of the automatic docstring tools just grab
everything. My approach has been to use the module documentation to
guide the hierarchy.
Thanks for the feedback. It really helps to get some.
More information about the Scipy-dev