Opened 12 years ago

Last modified 8 years ago

#8315 needs_info enhancement

Reference manual layout: toggles, sidebar links

Reported by: mpatel Owned by: mvngu
Priority: minor Milestone: sage-6.4
Component: documentation Keywords:
Cc: hivert, jhpalmieri, nthiery Merged in:
Authors: Mitesh Patel Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by 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.

Attachments (1)

trac_8315-doc_sidebar.patch (7.1 KB) - added by mpatel 12 years ago.
Reference manual toggles and sidebar links. sage repo.

Download all attachments as: .zip

Change History (13)

Changed 12 years ago by mpatel

Reference manual toggles and sidebar links. sage repo.

comment:1 Changed 12 years ago by mpatel

  • Authors set to Mitesh Patel
  • Cc hivert jhpalmiei nthiery added
  • Description modified (diff)
  • Milestone set to sage-4.3.3
  • Status changed from new to needs_review

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!

comment:2 Changed 12 years ago by mpatel

  • Cc jhpalmieri added; jhpalmiei removed

Oops!  Time for a break.

comment:3 Changed 12 years ago by 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.

comment:4 Changed 12 years ago by mpatel

  • Status changed from needs_review to needs_info

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

comment:5 Changed 12 years ago by mpatel

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

comment:6 Changed 12 years ago by 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!

comment:7 follow-up: Changed 12 years ago by nthiery

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

comment:8 in reply to: ↑ 7 Changed 12 years ago by 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?

comment:9 Changed 9 years ago by jdemeyer

  • Milestone changed from sage-5.11 to sage-5.12

comment:10 Changed 8 years ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:11 Changed 8 years ago by vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3

comment:12 Changed 8 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4
Note: See TracTickets for help on using tickets.