homepage

In the Windows help version of the docs that come with the Windows .msi
installer, the index pane to the left scrolls separately from the
content pane to the right. Very nice for jumping around even to other docs.
In the html versions at docs.python.org, there is one scroll bar and the
index disappears when one moves very far down the page. If sensibly
possible, decoupling index and context would be nice. Please pardon my
ignorance if not.

Terry, I think you mean the Sidebar content, right? 
Yes, I agree with you. It would be desirable to have the Sidebar
Fixed, while we scroll the document (Like this:
http://www.w3.org/Style/CSS/) 
This has to be worked out in the Sphnix CSS.

I've experimented with a style variant that keeps the sidebar fixed on
the left side, however I did not manage to get it to show a separate
scrollbar. Maybe I was just stupid though.

Something like this maybe?
div.sphinxsidebar {
 float: left;
 width: 230px;
 height: 100%;
 font-size: 90%
 /* add these: */
 margin-top: 30px;
 height: 100%;
 overflow: auto;
 position: fixed;
}
...
div.related {
 background-color: #133f52;
 color: #fff;
 width: 100%;
 line-height: 30px;
 font-size: 90%;
 /* add this: */
 position: fixed;
}
I tested it only with Firefox3 and the Webdeveloper plugin and it looks
ok. "position: fixed" doesn't work on IE6 and there could be other
problems, but it may be a good starting point.

See also #3143.
I'll try to do a proper patch to fix this issue.

"overflow: auto" should fix #4711 too (adding an horizontal scroll bar
at the bottom of the sidebar).

The attached patch makes the sidebar fixed and adds a scrollbar to scroll it separately when it's longer than the page.
To test the patch without rebuilding all the Docs you can do something like:
hg import --no-c <url-of-the-patch>
cp Doc/tools/sphinxext/static/basic.css Doc/build/html/_static/basic.css
firefox Doc/build/html/library/multiprocessing.html
Since the sidebar doesn't start at the top of the page because there's the header first, when the main page is scrolled down, some empty space is left over the sidebar. I think this can't be fixed with css alone (unless some major changes are done to the layout), it could be fixed with js or the header could use position:fixed too.

In the root of the clone, with the doc already built in Doc/build (no need to rebuild it), do:
hg import --no-c http://bugs.python.org/file27887/issue4965.diff
cp Doc/tools/sphinxext/static/basic.css Doc/build/html/_static/basic.css
firefox file://`pwd`/Doc/build/html/library/multiprocessing.html

See http://sphinx-doc.org/latest/ for my preferred solution.

I stole the code from that page and adapted it to integrate better with sidebar.js (and make it a bit more efficient).
To test the new patch, in the root of the clone, with the doc already built in Doc/build (no need to rebuild it), do:
hg import --no-c http://bugs.python.org/file32072/issue4965-2.diff
cp Doc/tools/sphinxext/static/sidebar.js Doc/build/html/_static/sidebar.js
cp Doc/tools/sphinxext/static/basic.css Doc/build/html/_static/basic.css
firefox file://`pwd`/Doc/build/html/library/multiprocessing.html

The patch seems to work well with both Safari 6.0.5 and Firefox 25.0 on OS X 10.8. Nice improvement.

Very nice, thanks for porting this. One minor nit: when I close the sidebar, then scroll and then reopen it, it does not immediately update the sidebar position, only when scrolling again.

You said you made it a bit more efficient; is this python-specific or can it be ported back to Sphinx?

> One minor nit: when I close the sidebar, then scroll and then reopen
> it, it does not immediately update the sidebar position, only when
> scrolling again.
I'll look into it.
> You said you made it a bit more efficient; is this python-specific
> or can it be ported back to Sphinx?
Some could be backported:
 * $('.sphinxsidebarwrapper'), $(window), and $('.sphinxsidebar') are re-evaluated every time the user scrolls. In sidebar.js I already had references to these, so I reused them; in Sphinx you can move them outside the .scroll();
 * The original code used $(window).innerHeight(), but the code in sidebar.js used window.innerHeight if available or $(window).height() if not. I kept the latter, however I'm not sure that is the best option;
 * $(document) and sidebar_height could also be calculated once at the beginning, since they shouldn't change, but I haven't done it in my patch;
 * In the patch I also renamed a few variables to be more clear;
 * The fix in #4711 could also be backported.

Updated patch should fix the nit and factors out $(document) from the scrolling function. Tested on Firefox and Chromium.

LGTM.

New changeset 3bb34d370871 by Ezio Melotti in branch '3.3':
#4965: Implement intelligent scrolling of the sidebar in the docs.
http://hg.python.org/cpython/rev/3bb34d370871
New changeset 8d916ea12efb by Ezio Melotti in branch 'default':
#4965: merge with 3.3.
http://hg.python.org/cpython/rev/8d916ea12efb 

I committed the patch on 3.3/3.x. I'm willing to port the patch on 2.7 too, however sidebar.js is not in Doc/tools/sphinxext/static/ but in Doc/tools/sphinx/themes/default/static/, which is not under version control. How do you suggest to proceed?

You'll have to put a copy in sphinxext/static.

New changeset d7ebe03fa752 by Ezio Melotti in branch '2.7':
#4965: Implement intelligent scrolling of the sidebar in the docs.
http://hg.python.org/cpython/rev/d7ebe03fa752 

Could you please make a scrolling more smooth? Or at least optional.

I've looked into it, and I found that:
1) the scroll event can be triggered dozens of times per second;
2) sidebarwrapper.css(...) causes a browser repaint/reflow, which is slow;
Optimizing the function doesn't seem like a good solution, so I tried to throttle it so that the position is updated at most once every 100ms (i.e. at 10fps max). On Firefox this shows that about 2-6 redraws are skipped but, as a side-effect, the sidebar might result a few pixels off due to the skipped redraws at the end (this doesn't seem noticeable though).
If the value is increased over 100ms these problems start being noticeable.
FTR there are more complex solutions but for now I preferred to keep it simple. These links contain other techniques (involving timers/timeouts):
* https://github.com/shichuan/javascript-patterns/blob/master/jquery-patterns/window-scroll-event.html
* http://underscorejs.org/docs/underscore.html#section-66 and http://underscorejs.org/#throttle
Serhiy, can you try to apply the patch and fiddle a bit with it to see if you notice any improvement? You can try to change 100 with a lower or higher value, or do last_call = new Date() at the end of scroll_sidebar(). You might also have to remove the calls to console.log() if they create problems on your browser.
Remember that after each change you have to do:
 cp Doc/tools/sphinxext/static/sidebar.js Doc/build/html/_static/sidebar.js
and refresh the page to see the results.

I don't notice any improvement. :(

I'm going to close this as fixed then.
If other people report problems I can always apply the patch and/or try to figure out something else.