Make the left sidebar in the doc collapsible

@birkenfeld

BPO	3143
Nosy	@birkenfeld, @orsenthil, @pitrou, @ashemedai, @ezio-melotti, @merwok, @bitdancer
Files	nosidebar.gif: Example doc page with collapsed sidebar. visible-vs-hidden.gif: Example doc page with visible and hidden sidebar. sidebar.js: JS file to make the sidebar collapsible. sidebar.zip: ZIP file that includes 3 HTML pages with the sidebar script.

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ezio-melotti'
closed_at = <Date 2010-07-30.11:31:22.859>
created_at = <Date 2008-06-19.16:48:49.482>
labels = ['type-feature', 'docs']
title = 'Make the left sidebar in the doc collapsible'
updated_at = <Date 2010-07-30.11:31:22.858>
user = 'https://bugs.python.org/forest'

bugs.python.org fields:

activity = <Date 2010-07-30.11:31:22.858>
actor = 'georg.brandl'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2010-07-30.11:31:22.859>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2008-06-19.16:48:49.482>
creator = 'forest'
dependencies = []
files = ['14789', '14790', '14804', '14805']
hgrepos = []
issue_num = 3143
keywords = []
message_count = 19.0
messages = ['68412', '68413', '68441', '68445', '68470', '86556', '86581', '89965', '92004', '92005', '92006', '92026', '92060', '92081', '102972', '102977', '103010', '106392', '112066']
nosy_count = 11.0
nosy_names = ['georg.brandl', 'orsenthil', 'pitrou', 'forest', 'wplapper', 'rdemetrescu', 'asmodai', 'jnoller', 'ezio.melotti', 'eric.araujo', 'r.david.murray']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'needs patch'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue3143'
versions = ['Python 2.6', 'Python 3.1', 'Python 2.7', 'Python 3.2']

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.

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 :-))

+1 coat to the bikeshed, the new layout is painful unless you're at a
higher resolution/bigger window

+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.

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.

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.

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. :)

Using "position: fixed" was requested in bpo-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.

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.

Attached a screenshot of the result.
I also made the top bar fixed as described in bpo-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 bpo-4965 though).

Another screenshot that shows the page with and without the sidebar,
with a "photoshopped" "<<" / ">>" button.

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).

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).

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.

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?

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.)

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.

Committed the sidebar.js to Sphinx trunk. When Python switches to 1.0, we can activate the option to use it. Thanks Ezio!

Now used in trunk docs, r83274.

Navigation Menu

Repository navigation

Make the left sidebar in the doc collapsible #47393

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Make the left sidebar in the doc collapsible #47393

Description

Activity

forest commented on Jun 19, 2008

pitrou commented on Jun 19, 2008

jnoller commented on Jun 20, 2008

orsenthil commented on Jun 20, 2008

birkenfeld commented on Jun 20, 2008

ashemedai commented on Apr 25, 2009

forest commented on Apr 26, 2009

ezio-melotti commented on Jul 1, 2009

ezio-melotti commented on Aug 27, 2009

ezio-melotti commented on Aug 27, 2009

ezio-melotti commented on Aug 27, 2009

ezio-melotti commented on Aug 28, 2009

ezio-melotti commented on Aug 29, 2009

ezio-melotti commented on Aug 30, 2009

forest commented on Apr 12, 2010

bitdancer commented on Apr 12, 2010

ezio-melotti commented on Apr 13, 2010

birkenfeld commented on May 24, 2010

birkenfeld commented on Jul 30, 2010

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions