classification
Title: Can doc index of html version be separately scrollable?
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder: Wide literals in the table of contents overflow in documentation
View: 4711
Assigned To: ezio.melotti Nosy List: ezio.melotti, georg.brandl, ned.deily, orsenthil, python-dev, serhiy.storchaka, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2009-01-16 23:30 by terry.reedy, last changed 2013-11-02 14:45 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue4965.diff ezio.melotti, 2012-11-04 23:31
issue4965-2.diff ezio.melotti, 2013-10-13 01:58
issue4965-3.diff ezio.melotti, 2013-10-13 19:49
issue4965-throttle.diff ezio.melotti, 2013-10-15 01:18
Messages (24)
msg79986 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2009-01-16 23:30
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.
msg80437 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2009-01-24 06:56
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.
msg81302 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-02-06 21:53
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.
msg81306 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-02-06 22:08
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.
msg89966 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-07-01 09:03
See also #3143.
I'll try to do a proper patch to fix this issue.
msg89971 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-07-01 10:20
"overflow: auto" should fix #4711 too (adding an horizontal scroll bar
at the bottom of the sidebar).
msg174843 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-04 23:31
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.
msg175230 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-09 12:39
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
msg199609 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-12 18:14
See http://sphinx-doc.org/latest/ for my preferred solution.
msg199650 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-10-13 02:01
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
msg199651 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2013-10-13 03:00
The patch seems to work well with both Safari 6.0.5 and Firefox 25.0 on OS X 10.8.  Nice improvement.
msg199659 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-13 07:00
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.
msg199660 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-13 07:00
You said you made it a bit more efficient; is this python-specific or can it be ported back to Sphinx?
msg199719 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-10-13 15:08
> 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.
msg199779 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-10-13 19:49
Updated patch should fix the nit and factors out $(document) from the scrolling function.  Tested on Firefox and Chromium.
msg199780 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-13 19:52
LGTM.
msg199825 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-14 00:00
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
msg199826 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-10-14 00:04
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?
msg199836 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-14 04:27
You'll have to put a copy in sphinxext/static.
msg199947 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-14 20:01
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
msg199956 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-10-14 21:24
Could you please make a scrolling more smooth? Or at least optional.
msg199971 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-10-15 01:18
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.
msg201489 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-10-27 20:08
I don't notice any improvement. :(
msg201974 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-11-02 14:45
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.
History
Date User Action Args
2013-11-02 14:45:39ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg201974

stage: commit review -> resolved
2013-10-27 20:08:39serhiy.storchakasetmessages: + msg201489
2013-10-15 01:18:37ezio.melottisetfiles: + issue4965-throttle.diff

messages: + msg199971
2013-10-14 21:24:32serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg199956
2013-10-14 20:01:33python-devsetmessages: + msg199947
2013-10-14 04:27:05georg.brandlsetmessages: + msg199836
2013-10-14 00:04:49ezio.melottisetmessages: + msg199826
stage: patch review -> commit review
2013-10-14 00:00:16python-devsetnosy: + python-dev
messages: + msg199825
2013-10-13 19:52:17georg.brandlsetmessages: + msg199780
2013-10-13 19:49:32ezio.melottisetfiles: + issue4965-3.diff

messages: + msg199779
2013-10-13 15:08:11ezio.melottisetmessages: + msg199719
2013-10-13 07:00:59georg.brandlsetmessages: + msg199660
2013-10-13 07:00:07georg.brandlsetmessages: + msg199659
2013-10-13 03:00:36ned.deilysetnosy: + ned.deily
messages: + msg199651
2013-10-13 02:01:22ezio.melottisetmessages: + msg199650
2013-10-13 01:58:55ezio.melottisetfiles: + issue4965-2.diff
2013-10-12 18:14:17georg.brandlsetmessages: + msg199609
2013-05-01 12:02:36ezio.melottisetversions: + Python 3.4, - Python 3.2
2013-01-22 12:44:49ezio.melottisetkeywords: + easy
stage: patch review
versions: - Python 3.1
2012-11-09 12:39:12ezio.melottisetmessages: + msg175230
2012-11-04 23:31:54ezio.melottisetfiles: + issue4965.diff
keywords: + patch
messages: + msg174843
2011-03-09 02:26:36terry.reedysetversions: + Python 3.3
2010-08-07 18:36:28terry.reedysetversions: - Python 2.6
2010-07-10 22:59:45terry.reedysetversions: + Python 3.2, - Python 3.0
2009-07-01 11:55:12ezio.melottisetpriority: normal
assignee: georg.brandl -> ezio.melotti
2009-07-01 10:20:12ezio.melottisetassignee: ezio.melotti -> georg.brandl
superseder: Wide literals in the table of contents overflow in documentation
messages: + msg89971
stage: needs patch -> (no value)
2009-07-01 09:03:39ezio.melottisetassignee: georg.brandl -> ezio.melotti
messages: + msg89966
stage: needs patch
2009-02-06 22:08:26ezio.melottisetnosy: + ezio.melotti
messages: + msg81306
2009-02-06 21:53:43georg.brandlsetmessages: + msg81302
2009-01-24 06:56:04orsenthilsetnosy: + orsenthil
messages: + msg80437
2009-01-16 23:30:32terry.reedycreate