UBY: show current location in navbar toctree

[westurner]

Add to:

• [x] local.js
  • [x] jquery.scrollTo https://github.com/flesler/jquery.scrollTo
• [x] sphinx template
  • [x] jquery.scrollTo
• [x] sphinx
  • [x] is jQuery a fair assumption?
  • [x] jquery.scrollTo

Code

• [x] CSS: a.youarehere { font-weight: bold; font-size: 1.4em; }
• [x] JS: update_navbar() { $(navbar a).removeClass('youarehere'); $(navbar a[href=<url>]).addClass('youarehere') }
  • [x] scrollto_navbar() { if $('#navbar').visible { scrollTo('#navbar a.youarehere'); }
• [x] JS: onReady(update_navbar)
• [x] JS: onHashChange(hash) { if hash!='#' { update_navbar })
• [x] JS: onClickTouch(a.youarehere) { update navbar }

Usability Justification

Show "you are here" to provide a visual affordance of the most recently selected heading:

• Navbar: Bold, Large Font
• Navbar (Mobile Dropdown): Bold, Large Font, Underline
• Content > Heading: arrow
  • ] [ widont

[westurner]

#TST

[westurner]

From https://westurner.org/2015/03/02/documentation:

• [x] UBY: show current location in navbar toctree (#6)

  gh:westurner/wiki#6

  https://github.com/westurner/wiki/issues/6

  • [o] [UBY] show the currently #manually-selected link in the navbar when the fixed navbar is scrolled beyond the viewport (i.e. when showing the complete table of contents in the full width sidebar navbar).
    • [x] Assert #anchor exists as a DOM_ element with an id="anchor" property.
    • [o] Find and style each link to #anchor (href="#anchor"):
      • [X] mobile header navbar:
        • [X] UBY: Bold and add an arrow ⬅ next to the heading, in place of the ¶ sphinx heading selector link.
      • [X] full width sidebar navbar:

        • [X] UBY: Bold and add an arrow ⬅ next to the heading, in place of the ¶ sphinx heading selector link.

        • [X] UBY: If the full width sidebar navbar is on the screen; and there's a link in the table of contents to the given #anchor; and that link is not displayed, scroll the sidebar navbar so that the given navbar link is displayed (with a few at the top, for context).

          .. code:: javascript

          ## pseudo-JS
          sidebar = $('#sidebar');
          link =  $(sidebar).find('a[href=<#anchor>]');
          if !(jquery.isonscreen.js(sidebar, link)) {
              jquery.scrollTo(sidebar, link);
          }
          

.. _DOM: https://wrdrd.com/docs/consulting/web-development#term-dom

• ] [ Learn Bootstrap_ ScrollSpy_ because it's already bundled with the bootstrap JS in sphinxjp.themes.basicstrap_.

  | Docs: http://getbootstrap.com/javascript/#scrollspy | Source: https://github.com/twbs/bootstrap/blob/master/js/scrollspy.js | JS: https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js | JS: https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js | CDNJS: https://cdnjs.com/libraries/twitter-bootstrap

  • ScrollSpy overwrites the currently #manually-selected link on scroll.
  • ScrollSpy synchronizes all page scroll action with navbar current link indication.
  • [ ] ScrollSpy does not work w/ a fixed navbar because #anchors are hidden (and otherwise remain scrolled out of the vieport without something like isonscreen and scrollTo (ENH?,TST)

.. _Bootstrap: https://github.com/twbs/bootstrap .. _ScrollSpy: http://getbootstrap.com/javascript/#scrollspy

• ] [ Learn ReadTheDocs_ in order to WriteTheDocs_:

  • The default ReadTheDocs theme is sphinx_rtd_theme.

    | Source: git https://github.com/snide/sphinx_rtd_theme | PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme | Docs: https://read-the-docs.readthedocs.org/en/latest/theme.html

  • Sphinx themes are configured in a conf.py file. From http://stackoverflow.com/a/25007833 (CC-BY-SA 3.0):

    .. code:: python

    # on_rtd is whether we are on readthedocs.org
    import os
    on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
    
    if not on_rtd:  # only import and set the theme if we're building docs locally
        import sphinx_rtd_theme
        html_theme = 'sphinx_rtd_theme'
        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
    
    # otherwise, readthedocs.org uses their theme by default, so no need to specify it
    

  • From casual inspection, ReadTheDocs rtd_theme takes a different approach:

    • ReadTheDocs rtd_theme does support scrolling the left navbar independently from the document;
    • ReadTheDocs rtd_theme scrolls the navbar and the document;
    • The ReadTheDocs rtd_theme navbar displays a document-expanded but otherwise collapsed table of contents.

.. _ReadTheDocs: https://read-the-docs.readthedocs.org/en/latest/ .. _WriteTheDocs: http://www.writethedocs.org/ .. _WriteTheDocs 2015 videos: https://www.youtube.com/playlist?list=PLkQw3GZ0bq1JvhaLqfBqRFuaY108QmJDK

[westurner]

• [ ] Define/determine behavior when refreshing with #fragment-links . e.g. does it preserve scroll:
  • on refresh/reload
  • on back/forward