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: |
Description (last modified by )
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)
Change History (13)
Changed 12 years ago by
comment:1 Changed 12 years ago by
- 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:3 Changed 12 years ago by
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
- 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
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
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: ↓ 8 Changed 12 years ago by
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
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
- Milestone changed from sage-5.11 to sage-5.12
comment:10 Changed 8 years ago by
- Milestone changed from sage-6.1 to sage-6.2
comment:11 Changed 8 years ago by
- Milestone changed from sage-6.2 to sage-6.3
comment:12 Changed 8 years ago by
- Milestone changed from sage-6.3 to sage-6.4
Reference manual toggles and sidebar links. sage repo.