classification
Title: Make the left sidebar in the doc collapsible
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: asmodai, eric.araujo, ezio.melotti, forest, georg.brandl, jnoller, orsenthil, pitrou, r.david.murray, rdemetrescu, wplapper
Priority: normal Keywords:

Created on 2008-06-19 16:48 by forest, last changed 2010-07-30 11:31 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
nosidebar.gif ezio.melotti, 2009-08-27 15:23 Example doc page with collapsed sidebar.
visible-vs-hidden.gif ezio.melotti, 2009-08-27 15:36 Example doc page with visible and hidden sidebar.
sidebar.js ezio.melotti, 2009-08-30 05:57 JS file to make the sidebar collapsible.
sidebar.zip ezio.melotti, 2009-08-30 05:59 ZIP file that includes 3 HTML pages with the sidebar script.
Messages (19)
msg68412 - (view) Author: Forest (forest) Date: 2008-06-19 16:48
I was just browsing the development docs, and noticed that the new
left-side navigation bar wastes a lot of horizontal space on the web
page.  It fills nearly a third of my browser window (at its usual size)
with useless blank space, at the expense of the pertinent information. 
This makes it harder to get much use out of a docs window placed next to
my editor window, since I am now forced to switch active windows and/or
scroll around the docs window in order to read the section I'm working
with.  In a few cases, it leaves space for so few words per line that
even the visible part of the docs actually become harder to read
(especially with text justification).

For comparison, here are screen shots from the old and new documentation:
http://hestiafire.org/forest/img/doc25.png
http://hestiafire.org/forest/img/doc26.png

Is this side bar going to be present in the final release of the python
2.6 docs?  I hope not.  It's a significant loss in readability, IMHO.
msg68413 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2008-06-19 17:07
I agree with this bug entry. Also, since pages are usually long, if the
left nav bar is really to be useful it should use some "fixed"
positioning in the CSS (that is, doesn't move when the rest of the page
is scrolled).

(of course this could also be considered bikeshedding :-))
msg68441 - (view) Author: Jesse Noller (jnoller) * (Python committer) Date: 2008-06-20 02:03
+1 coat to the bikeshed, the new layout is painful unless you're at a 
higher resolution/bigger window
msg68445 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2008-06-20 03:33
+1 to support this bug entry. Even though I have wide-monitor (1680x1050), keeping such a wide left side margin is a pain when reading the new docs. I was looking for the settings if there is any way to turn off the left navigation or change the CSS style to a more plain one. Nope, it is not there.
msg68470 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-06-20 20:13
I know about this and will think about possible ways out of it. Of
course if someone has a patch it will probably be faster.
msg86556 - (view) Author: Jeroen Ruigrok van der Werven (asmodai) * (Python committer) Date: 2009-04-25 21:22
I assume this is relative to the resolution of a user's monitor. For me,
using the current documentation it only takes about 1/8th - 1/9th of my
width.
msg86581 - (view) Author: Forest (forest) Date: 2009-04-26 01:02
It is relative to the resolution of the user's browser window.  Don't
make the mistake of assuming that everyone keeps their browser
maximized.  :)
msg89965 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-07-01 09:01
Using "position: fixed" was requested in #4965 too and I posted a proof
of concept. I'll try to do a proper patch in the next days.

It might also be possible to make the sidebar collapsible using
Javascript (something similar to the sidebar of Google maps).
I'll take a look at this issue too.
msg92004 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-08-27 15:07
I just did a quick test about making the sidebar collapsible.
Add these lines at the end of default.css to see how the page might look
like with the sidebar collapsed:

/* collapse the sidebar */
div.sphinxsidebar {
    /* border: 3px solid red; */
    width: 1em !important;
}
/* hide the content of the sidebar */
div.sphinxsidebarwrapper {
    display: none;
}
/* expand the page to use the sidebar space */
div.bodywrapper{
    /* border: 3px solid blue; */
    margin-left: 1em !important;
}

A "<<" / ">>" button has to be added (via JS) to collapse and restore
the sidebar. The CSS properties have to be changed via JS too, the users
without JS won't notice any difference at all.
When the sidebar is collapsed, it is possible to make it appear again
clicking anywhere on the 1em-wide collapsed sidebar on the left (and not
only on the ">>").
The sidebar could be hidden completely by placing the "<<" / ">>" button
or an "Hide/Show sidebar" link in the top-left corner, but I don't know
exactly where (before the small python icon? just under it in a
"floating box"?).

The WebDeveloper plug-in of Firefox can be used to see the changes on
the fly (CSS -> Edit CSS -> paste the code at the end of default.css),
otherwise you can edit the CSS manually.
Feedback and comments appreciated.
msg92005 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-08-27 15:23
Attached a screenshot of the result.
I also made the top bar fixed as described in #4965, so it's always
visible even if the user scrolled till the middle of the page (this is
not related to this issue and will be addressed in #4965 though).
msg92006 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-08-27 15:36
Another screenshot that shows the page with and without the sidebar,
with a "photoshopped" "<<" / ">>" button.
msg92026 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-08-28 03:51
Attached a first attempt to make the sidebar collapsible.
The sidebar.js file is the JS script I did, the sidebar.zip file
contains a couple of pages taken from the doc with the sidebar scripts
already included in a <script>.

If you want to try it just extract the files, open the *.html with a
browser and it should work.

This is not supposed to be the final version, I tested it only on FF3
(where it seems to work fine) and on IE6 (where it is as broken as you
would expect). This is also the first time I use JQuery, so any comments
and suggestions are welcomed (both about the code and the result).
msg92060 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-08-29 07:31
Here's a new version. Now it works with all the major browsers and it's
more usable.

I tested it on the following browsers, and I didn't notice any problem/bug:
Firefox 2.0/3.0/3.5;
Internet Explorer 6/7/8;
Opera 9.64;
Chrome 2.0;
Konqueror 4.2.2;
Seamonkey 1.1;

I also tested it on a Nokia 5800, where the sidebar normally takes more
than half of the screen or about 1/3 if the phone is in landscape mode
(its screen resolution is 640x360, the sidebar is 230px).
With the built-in browser it works fine, but it's quite slow (8-9
seconds to collapse and a few more seconds to expand).
With Opera Mini it has some problem: when the sidebar is collapsed the
page is reloaded and the only way to expand it again is to use the
'back' button.

A few things could be improved:
  * Add some "effects" to the button on hover (to show that it is
clickable) and on click (to show that it was clicked);
  * Remember the position of the sidebar (collapsed/expanded) in all the
pages of the doc (using a cookie?);
  * Make it faster (although I think that most of the time is spent
rendering the page, so there's probably nothing to do).
msg92081 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-08-30 05:57
This should be the final version, these are the things I improved:
  * added a per-browser/per-session cookie to save the position of the
sidebar during a single session. When the browser is closed the position
is reset and the cookie deleted;
  * added an effect on hover and a better vertical centering of the '<<'
/ '>>';
  * fixed some bugs.

I also tried to make it faster (with no appreciable results).

I tested it on the aforementioned browsers and it seems to work fine, so
if there are no comments on the code or on the final result, the script
is ready to go in.
msg102972 - (view) Author: Forest (forest) Date: 2010-04-12 20:51
I just noticed Ezio's change to the title of this bug.  Does the proposed fix address the original bug title ("docs waste a lot of horizontal space on left nav bar") for third-party packages that use docutils to generate their docs?  Or, does it only avoid the problem in the official python documentation?
msg102977 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-04-12 21:52
I'm pretty sure it only applies to the python docs, since this is the Python tracker, not the Sphinx or docutils tracker.  (I'm not sure how the 'Documentation tools (Sphinx)' component gets in there...as far as I know Sphinx bugs go the Sphinx bug tracker.)
msg103010 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-04-13 04:14
Even if I tested it only with Python documentation, the script should work for other docs generated by Sphinx (at least with the default theme).
Last time I tried the script it wasn't working on Chrome, so there's still some work to do. If you want to try it and see if it works with your doc, it should be enough to copy the .js file and include it in the HTML page using a <script> tag.
msg106392 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-05-24 21:16
Committed the sidebar.js to Sphinx trunk.  When Python switches to 1.0, we can activate the option to use it.  Thanks Ezio!
msg112066 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-07-30 11:31
Now used in trunk docs, r83274.
History
Date User Action Args
2010-07-30 11:31:22georg.brandlsetstatus: open -> closed
resolution: remind -> fixed
messages: + msg112066
2010-07-11 02:23:22terry.reedysetnosy: georg.brandl, orsenthil, pitrou, forest, wplapper, rdemetrescu, asmodai, jnoller, ezio.melotti, eric.araujo, r.david.murray
components: - Documentation tools (Sphinx)
2010-05-24 21:16:26georg.brandlsetresolution: remind
messages: + msg106392
2010-04-13 04:14:28ezio.melottisettype: enhancement
messages: + msg103010
2010-04-12 21:52:37r.david.murraysetnosy: + r.david.murray

messages: + msg102977
versions: + Python 3.2, - Python 3.0
2010-04-12 20:51:54forestsetmessages: + msg102972
2009-08-30 05:59:34ezio.melottisetfiles: + sidebar.zip
2009-08-30 05:57:49ezio.melottisetfiles: + sidebar.js

messages: + msg92081
2009-08-30 05:43:00ezio.melottisetfiles: - sidebar.js
2009-08-30 05:42:55ezio.melottisetfiles: - sidebar-old.js
2009-08-30 05:40:24ezio.melottisetfiles: - sidebar.zip
2009-08-29 07:33:05ezio.melottisetfiles: + sidebar.zip
2009-08-29 07:32:34ezio.melottisetfiles: - sidebar.zip
2009-08-29 07:31:52ezio.melottisetfiles: + sidebar.js

messages: + msg92060
2009-08-28 03:51:54ezio.melottisetpriority: low -> normal
files: + sidebar.zip
messages: + msg92026
2009-08-28 03:38:15ezio.melottisetfiles: + sidebar-old.js
title: development docs waste a lot of horizontal space on left nav bar -> Make the left sidebar in the doc collapsible
2009-08-27 15:36:37ezio.melottisetfiles: + visible-vs-hidden.gif

messages: + msg92006
2009-08-27 15:23:26ezio.melottisetfiles: + nosidebar.gif

messages: + msg92005
2009-08-27 15:07:38ezio.melottisetmessages: + msg92004
2009-07-01 09:01:31ezio.melottisetpriority: low
versions: + Python 3.1, Python 2.7
messages: + msg89965

assignee: georg.brandl -> ezio.melotti
stage: needs patch
2009-07-01 08:48:55ezio.melottisetnosy: + ezio.melotti
2009-04-28 15:42:36eric.araujosetnosy: + eric.araujo
2009-04-26 01:02:08forestsetmessages: + msg86581
2009-04-25 21:22:21asmodaisetnosy: + asmodai
messages: + msg86556
2008-10-22 20:41:18wplappertsetnosy: + wplapper
2008-06-24 13:45:21rdemetrescusetnosy: + rdemetrescu
2008-06-20 20:13:08georg.brandlsetmessages: + msg68470
components: + Documentation tools (Sphinx)
2008-06-20 03:33:08orsenthilsetnosy: + orsenthil
messages: + msg68445
2008-06-20 02:03:37jnollersetnosy: + jnoller
messages: + msg68441
2008-06-19 17:07:28pitrousetnosy: + pitrou
messages: + msg68413
2008-06-19 16:48:49forestcreate