Wes Turner

westurner

Documentation

This weekend, I managed to get a fixed navigation bar configured with the Bootstrap affix JS and a fair amount of CSS iteration for Sphinx (with the excellent sphinxjp.themes.basicstrap) and have been merging the new styles into various sets of docs that I’ve been working on:

Update: 2015-07-04

  • [X] DOC: 2015/03/02/documentation.rst: Update inlined WRD R&D Documentation Table of Contents

  • [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).

            ## pseudo-JS
            sidebar = $('#sidebar');
            link =  $(sidebar).find('a[href=<#anchor>]');
            if !(jquery.isonscreen.js(sidebar, link)) {
                jquery.scrollTo(sidebar, link);
            }
            
  • [ ] Learn ReadTheDocs in order to WriteTheDocs:

    • The default ReadTheDocs theme is sphinx_rtd_theme.

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

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