[SciPy-dev] Fledgling livedocs website

[Travis Oliphant]

Arnd Baecker wrote:

>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
>  
>
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 
inspect.getcomments).

>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
>
>  
>
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
>'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))
>  
>
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 
from before).

>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 ....)
>  
>
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. 

-Travis