Documentation is pretty hard to read...

[Nathann Cohen]

Hello everybody !!!!

I had a question to ask about the documentation we produce for Sage from the docstrings.... When I look at page :
http://sagemath.org/doc/reference/sage/graphs/graph.html#graph-format
I am, well.. A bit scared... I have something like one hundred screens of descriptions of functions, examples for all of them, etc.... It is pretty useful, but could it be possible to display it differently ?

Wouldn't you think it would be easier to read if we only had the list of methods displayed on this page, and a + sign on the left to show the details of a particular function (and a - to hide them) ?

It is not that hard to write in Javascript  ( even if the problem of having to load such a huge page remains ), and it would greatly improve the "readability" ( does this word exist in english ? O_o ).

It could be done in Ajax too, but this is more something to be done on Sphynx's side...

Thank youuuuuuuu !! :-)

Nathann

[Pat LeSmithe]

Nathann Cohen wrote:
> I had a question to ask about the documentation we produce for Sage from the

A dynamic, lazy-loading, live documentation browser and/or object
inspector could be useful. Which layouts are appropriate? Can we use
existing libraries?

Trees

http://api.jquery.com/
http://www.jstree.com/

Miller columns

http://en.wikipedia.org/wiki/Miller_Columns
http://www.smartclient.com/smartgwt/showcase/#featured_miller_columns

I'm sure there are others. The last is actually a Google Web Toolkit
(GWT) extension written in Java. Can anyone point out a similar
JavaScript widget?

Individual topics could float freely or occupy tab widget, say, or even
browser tabs. We could save bookmarks and configurations on the server.

Unless I'm mistaken, the notebook's introspection system already
provides much of what we need to set this up. We "just" need to create an
altogether differently organized "worksheet."