UBY: show current location in navbar toctree

[westurner]

Add to:

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

Code

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

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

  gh:westurner/wiki#6

  UBY: show current location in navbar toctree #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).
    • Assert #anchor exists as a DOM_ element
      with an id="anchor" property.
    • [o] Find and style each link to #anchor (href="#anchor"):
      • mobile header navbar:
        • UBY: Bold and add an arrow ⬅
          next to the heading,
          in place of the ¶ sphinx heading selector link.
      • full width sidebar navbar:

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

        • 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