[SciPy-dev] Fledgling livedocs website

Arnd Baecker 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
(html?)?
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
or happydoc,
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 ...))

Best,

Arnd




More information about the Scipy-dev mailing list