Make the left sidebar in the doc collapsible

[forest]

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']

[forest]

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.

[pitrou]

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

[jnoller]

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

[orsenthil]

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

[birkenfeld]

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.

[ashemedai]

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.

[forest]

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

[ezio-melotti]

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.

[ezio-melotti]

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.

[ezio-melotti]

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