UBY: show current location in navbar toctree #6

Open
westurner opened this Issue Jun 8, 2015 · 3 comments

Comments

Projects
None yet
1 participant
@westurner
Owner

westurner commented Jun 8, 2015

Add to:

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 westurner added UBY ENH labels Jun 8, 2015

@westurner westurner self-assigned this Jun 9, 2015

westurner added a commit that referenced this issue Jun 10, 2015

westurner added a commit that referenced this issue Jun 10, 2015

westurner added a commit that referenced this issue Jun 10, 2015

@westurner westurner modified the milestone: 0.2 Jun 10, 2015

westurner added a commit to wrdrd/docs that referenced this issue Jun 15, 2015

@westurner

This comment has been minimized.

Show comment
Hide comment
@westurner

westurner Jul 7, 2015

Owner

#TST

Owner

westurner commented Jul 7, 2015

#TST

@westurner

This comment has been minimized.

Show comment
Hide comment
@westurner

westurner Jul 7, 2015

Owner

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

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

    gh:westurner/wiki#6

    #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

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

Owner

westurner commented Jul 7, 2015

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

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

    gh:westurner/wiki#6

    #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

.. _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 added a commit to westurner/westurner.github.io that referenced this issue Nov 18, 2015

@westurner

This comment has been minimized.

Show comment
Hide comment
@westurner

westurner Dec 22, 2015

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

westurner commented Dec 22, 2015

  • Define/determine behavior when refreshing with #fragment-links . e.g. does it preserve scroll:
    • on refresh/reload
    • on back/forward
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment