Merge branch 'master' into menu-aria-expanded

README.rst

@@ -33,21 +33,15 @@ This theme is distributed on PyPI_ and can be installed with ``pip``:
 
    $ pip install sphinx-rtd-theme
 
-To use the theme in your Sphinx project, you will need to add the following to
-your ``conf.py`` file:
+To use the theme in your Sphinx project, you will need to edit
+your ``conf.py`` file's ``html_theme`` setting:
 
 .. code:: python
 
-    import sphinx_rtd_theme
-
-    extensions = [
-        ...
-        "sphinx_rtd_theme",
-    ]
-
     html_theme = "sphinx_rtd_theme"
 
-For more information read the full documentation on `installing the theme`_
+For more information, including a full example with localized strings enabled,
+read the documentation on `installing the theme`_.
 
 .. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
 .. _installing the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html

sphinx_rtd_theme/__init__.py

@@ -55,4 +55,10 @@ def setup(app):
         app.add_message_catalog('sphinx', rtd_locale_path)
         app.connect('config-inited', config_initiated)
 
+    # sphinx emits the permalink icon for headers, so choose one more in keeping with our theme
+    if sphinx_version >= (3, 5, 0):
+        app.config.html_permalinks_icon = "\uf0c1"
+    else:
+        app.config.html_add_permalinks = "\uf0c1"
+
     return {'parallel_read_safe': True, 'parallel_write_safe': True}

src/sass/_theme_layout.sass

@@ -64,14 +64,17 @@ html
       padding-left: 0
       padding-right: 0
     // Expand links
-    span.toctree-expand
+    button.toctree-expand
       display: block
       float: left
       margin-left: -1.2em
       @extend .fa
       @extend .fa-plus-square-o
       line-height: 18px
       color: darken($menu-link-medium, 20%)
+      border: none
+      background: none
+      padding: 0
 
   // On state for the first level
   li.on a, li.current > a
@@ -85,9 +88,9 @@ html
     +font-smooth
     &:hover
       background: $menu-vertical-background-color
-      span.toctree-expand
+      button.toctree-expand
         color: $menu-link-medium
-    span.toctree-expand
+    button.toctree-expand
       @extend .fa
       @extend .fa-minus-square-o
       display: block
@@ -134,7 +137,7 @@ html
             @extend %display_current_toctree_element
             padding: ($gutter / 4) ($gutter * ($toc_level + 0.5))
             padding-right: $gutter
-        a:hover span.toctree-expand
+        a:hover button.toctree-expand
           @extend %toctree_hover_link_color
     @if $toc_level > 2 and $toc_level < 5
       li.toctree-l#{$toc_level}
@@ -146,15 +149,15 @@ html
         background: darken($menu-vertical-background-color, 20%)
       li.toctree-l3 > a
         background: darken($menu-vertical-background-color, 20%)
-    span.toctree-expand
+    button.toctree-expand
       color: darken($menu-vertical-background-color, 35%)
   li.toctree-l3
     &.current
       > a
         background: darken($menu-vertical-background-color, 25%)
       li.toctree-l4 > a
         background: darken($menu-vertical-background-color, 25%)
-    span.toctree-expand
+    button.toctree-expand
       color: darken($menu-vertical-background-color, 40%)
 
   li.current ul
@@ -176,13 +179,13 @@ html
     &:hover
       background-color: lighten($menu-background-color, 10%)
       cursor: pointer
-      span.toctree-expand
+      button.toctree-expand
         color: $menu-link-light
     &:active
       background-color: $menu-logo-color
       cursor: pointer
       color: $menu-link-active
-      span.toctree-expand
+      button.toctree-expand
         color: $menu-link-active
 
 .wy-side-nav-search

src/sass/_theme_rst.sass

@@ -200,14 +200,19 @@
   // This is the #href that shows up on hover. Sphinx's is terrible so I hack it away.
   h1, h2, h3, h4, h5, h6, dl dt, p.caption, table > caption, .code-block-caption
     .headerlink
-      visibility: hidden
+      opacity: 0
       font-size: 14px
+      font-family: FontAwesome
+      margin-left: 0.5em
       @extend .fa
-      &:after
-        content: "\f0c1"
-        font-family: FontAwesome
-    &:hover .headerlink:after
-      visibility: visible
+      &:focus
+        opacity: 1
+    &:hover .headerlink
+      opacity: 1
+
+  // override the Wyrm accessibility anti-pattern of hiding button focus
+  .btn:focus
+    outline: 2px solid
 
   table > caption .headerlink:after
     font-size: 12px

src/theme.js

@@ -112,7 +112,8 @@ function ThemeNav () {
         // Add expand links to all parents of nested ul
         $('.wy-menu-vertical ul').not('.simple').siblings('a').each(function () {
             var link = $(this);
-                expand = $('<span class="toctree-expand"></span>');
+                expand =
+                    $('<button class="toctree-expand" title="Open/close menu"></button>');
             expand.on('click', function (ev) {
                 self.toggleCurrent(link);
                 ev.stopPropagation();