Reference manual layout: toggles, sidebar links

[mpatel]

We add potentially useful features to reference manual HTML pages:

• In the sidebar:
  • Sticky sidebar toggle.
  • Indented list of links to the page's classes, methods, functions.
  • Controls to toggle, hide, or show docstrings.
• In the main content:
  • Click on an argspec to toggle the corresponding docstring.

See ​sage-devel for some background.

[mpatel]

Reference manual toggles and sidebar links. sage repo.

[mpatel]

I've attached a first take. Remarks:

• I haven't tested this extensively.
• The sticky sidebar doesn't work in the live docs.
• All of the transformations are done in the browser when it renders the page.
• Feel free to change the colors or suggest other changes!

[mpatel]

Oops!  Time for a break.

[mpatel]

To do:

• Disable or fix the sticky sidebar in the live docs.
• Add hide / show / toggle controls for "all."
• Add a color, etc., for attributes (e.g., aliases), data, exceptions, modules, i.e., the other autodocumenters.
• Fix uniform over-indentation in live docs.
• Make (sub)section headings toggle (sub)section display. We can use this in the other docs.
• Add "larger" and "smaller" font size controls.
• When it's necessary, extend the main content to match the sidebar in length.

Most of these are straightforward to implement, I think.

[mpatel]

I'm changing this to "needs info" until I can determine which improvements to make.

[mpatel]

​Here is the Sage 4.5.rc1 HTML reference manual built with the patch above. See, for example, ​2D Plotting. Comments are welcome!

[nthiery]

Wow, I haven't tried it intensively, but for what I saw, it's going to be a great improvement in usability of the doc! Thanks!

[nthiery]

Oh, by the way: would it be hard to add a pointer to the corresponding live documentation, when available?

[mpatel]

Replying to nthiery:

Oh, by the way: would it be hard to add a pointer to the corresponding live documentation, when available?

Good idea! This should be straightforward. It may be better to include the link in just the "fast static" documentation. In this case, we have the server address and port number, so we can insert an analogous "Go live!" link on the fly.

Of course, this only works if the server is still running and works best when the user is logged into the server. I'm not aware of an easy way for a page to check whether a link is valid before deciding whether to display it or hide it.

For the "offline" docs (e.g., those accessed via file:///), perhaps we could prompt for a working server address (and save it in a cookie) or direct the user to sagenb.org?