[SciPy-dev] Fledgling livedocs website
arnd.baecker at web.de
Sun Nov 7 06:58:48 CST 2004
On Sat, 6 Nov 2004, Travis Oliphant wrote:
> Arnd Baecker wrote:
> >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).
Do you have one separate routine which takes the doc-string of
a module, modifies it a bit, and then returns the result
If so, one could try to built loop around this
which recursively extracts all the information found there
and creates a set of html-pages
- hmm, this sounds like redoing an epydoc
at least in one part.
> >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.
I like this - one gets a nice overview about scipy
((just before I forget this thought (google can remind me;-):
Actually, maybe one could also integrate this into documancer -
it has the concept of "providers", which provide the information.
For example presently there is a pydoc provider to access documentation
on python stuff. However, it screws up on scipy -
I don't really know why ...))
More information about the Scipy-dev