Hi Jason, On Wed, Mar 10, 2010 at 3:58 AM, Jason Bandlow <jband...@gmail.com> wrote:
<SNIP> > 1) Remove the 'subtopics' from the current index. I.e., when opening > the reference manual, one would just see links: > > * The Sage Command Line > * The Sage Notebook > * Symbolic Calculus > ... > > Ideally, these would be sorted in some way that the user can understand, > alphabetically perhaps (although it might be good to keep the first two > topics at the top). The current format is difficult for a human to > search through efficiently since it is very long and in an apparently > random order. I think this is a matter of configuring the table of contents (TOC). At the moment, the index.rst file of the reference manual is configured to have a TOC level of 2. The effect is to show topics and subtopics. If instead the TOC were to be changed to 1, then only topics would be displayed. I think that changing the TOC depth of the reference manual, while trivial to do, requires a vote. > 2) On opening a topic, the first links should be (if they exist) > * Quickref > * Primer > * Tutorial > > I find this kind of documentation extremely useful, and this seems to me > the most likely place for a user browsing for 'conceptual help' to find > them. That sure hits the spot. Usually, after clicking on a topic link, I want some quick help on the overall features of the module covered by the topic. > 3) Introspection with '?', '??', and '.<tab>' is fast and awesome and it > should definitely be possible to get to any relevant documentation this > way. (See Nicolas' suggestions above.) The only problem I currently > have, is that there are currently not enough 'global hooks' in the > docstrings. In Mathematica, for example, if one asks for help on a > command, one ends up in the appropriate place in the manual, and it is > easy to 'back out' to find related commands. This is trickier in sage. > Recently, in sage, I wanted to plot a torus. I opened sage and did > 'plot<tab>' --> 'plot3d?' only to realize that this wasn't the function > I wanted. Unfortunately, the documentation here gave no hint that I > there was a command called 'implicit_plot3d'... I eventually found it > via the reference manual, but it was a little annoying. In retrospect, > I could have found it with sage.plot.plot3d.<tab> but I don't think this > is particularly obvious. I would love to see a more-or-less-standard > section in doctrings: > > SEE ALSO:: > > :mod:`sage.foo.bar1` > :mod:`sage.foo.bar2` > :mod:`sage.foo` > > where the documentation for 'sage.mod.submod.function' basically always > refers back to 'sage.mod.submod', at least. Even better would be if, in > the HTML doc, these were clickable links. Documentation writers are encouraged to liberally use the ReST syntax ".. SEEALSO" -- Regards Minh Van Nguyen -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
