Merge branch 'master' into new-cssnew-css

9 files changed, 86 insertions, 47 deletions

diff --git a/README.rst b/README.rst
index dcc8078..dcc16cd 100644
--- a/README.rst
+++ b/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
diff --git a/docs/configuring.rst b/docs/configuring.rst
index d7dcaf3..7e22c5b 100644
--- a/docs/configuring.rst
+++ b/docs/configuring.rst
@@ -13,7 +13,7 @@ For example:
 .. code:: python
 
     html_theme_options = {
-        'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
+        'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
         'analytics_anonymize_ip': False,
         'logo_only': False,
         'display_version': True,
@@ -96,11 +96,13 @@ Miscellaneous options
 
 .. confval:: analytics_id
 
-    If specified, Google Analytics' javascript is included in your pages.
-    Set the value to the ID provided to you by google (like ``UA-XXXXXXX``).
+    If specified, Google Analytics' `gtag.js`_ is included in your pages.
+    Set the value to the ID provided to you by google (like ``UA-XXXXXXX`` or ``G-XXXXXXXXXX``).
 
     :type: string
 
+    .. _gtag.js: https://developers.google.com/gtagjs
+
 .. confval:: analytics_anonymize_ip
 
     Anonymize visitor IP addresses in Google Analytics.
diff --git a/docs/installing.rst b/docs/installing.rst
index 759e73a..61aaac1 100644
--- a/docs/installing.rst
+++ b/docs/installing.rst
@@ -49,6 +49,14 @@ Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into you
 Compatibility
 =============
 
+Python
+------
+
+``sphinx_rtd_theme`` requires Python 2.7 or Python 3.4 or greater.
+
+Sphinx
+------
+
 ``sphinx_rtd_theme`` depends on at least Sphinx 1.6 although,
 we recommend at least Sphinx 2 to take advantage of the html5 writer.
 The html4 writer is still supported however,
diff --git a/setup.py b/setup.py
index 202444a..39f3937 100644
--- a/setup.py
+++ b/setup.py
@@ -106,7 +106,7 @@ setup(
         'theme.conf',
         '*.html',
         'static/css/*.css',
-        'static/css/fonts/*.*'
+        'static/css/fonts/*.*',
         'static/js/*.js',
     ]},
     include_package_data=True,
@@ -116,6 +116,7 @@ setup(
             'sphinx_rtd_theme = sphinx_rtd_theme',
         ]
     },
+    python_requires='>=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*',
     install_requires=[
         'sphinx>=1.6',
         'docutils<0.17', # https://github.com/sphinx-doc/sphinx/issues/9001
diff --git a/sphinx_rtd_theme/__init__.py b/sphinx_rtd_theme/__init__.py
index b7a4bb9..f254c4e 100644
--- a/sphinx_rtd_theme/__init__.py
+++ b/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}
diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html
index a61e51b..2ca84a6 100644
--- a/sphinx_rtd_theme/layout.html
+++ b/sphinx_rtd_theme/layout.html
@@ -219,17 +219,15 @@
   {%- if not READTHEDOCS %}
     {%- if theme_analytics_id %}
     <!-- Theme Analytics -->
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{ theme_analytics_id }}"></script>
     <script>
-    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
-      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
-      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
-    })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
-
-    ga('create', '{{ theme_analytics_id }}', 'auto');
-    {%- if theme_analytics_anonymize_ip|tobool %}
-    ga('set', 'anonymizeIp', true);
-    {%- endif %}
-    ga('send', 'pageview');
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+
+      gtag('config', '{{ theme_analytics_id }}', {
+          'anonymize_ip': {{ 'true' if theme_analytics_anonymize_ip|tobool else 'false' }},
+      });
     </script>
 
     {%- endif %}
diff --git a/src/sass/_theme_layout.sass b/src/sass/_theme_layout.sass
index b387935..b1c47c3 100644
--- a/src/sass/_theme_layout.sass
+++ b/src/sass/_theme_layout.sass
@@ -64,7 +64,7 @@ html
       padding-left: 0
       padding-right: 0
     // Expand links
-    span.toctree-expand
+    button.toctree-expand
       display: block
       float: left
       margin-left: -1.2em
@@ -72,6 +72,9 @@ html
       @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,7 +149,7 @@ 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
@@ -154,7 +157,7 @@ html
         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
diff --git a/src/sass/_theme_rst.sass b/src/sass/_theme_rst.sass
index 047e7eb..f02b7c4 100644
--- a/src/sass/_theme_rst.sass
+++ b/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
diff --git a/src/theme.js b/src/theme.js
index 2f01334..504fa64 100644
--- a/src/theme.js
+++ b/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();
@@ -144,11 +145,19 @@ function ThemeNav () {
             // If we found a matching link then reset current and re-apply
             // otherwise retain the existing match
             if (link.length > 0) {
-                $('.wy-menu-vertical .current').removeClass('current');
-                link.addClass('current');
-                link.closest('li.toctree-l1').parent().addClass('current');
+                $('.wy-menu-vertical .current')
+                    .removeClass('current')
+                    .attr('aria-expanded','false');
+                link.addClass('current')
+                    .attr('aria-expanded','true');
+                link.closest('li.toctree-l1')
+                    .parent()
+                    .addClass('current')
+                    .attr('aria-expanded','true');
                 for (let i = 1; i <= 10; i++) {
-                    link.closest('li.toctree-l' + i).addClass('current');
+                    link.closest('li.toctree-l' + i)
+                        .addClass('current')
+                        .attr('aria-expanded','true');
                 }
                 link[0].scrollIntoView();
             }
@@ -187,13 +196,26 @@ function ThemeNav () {
 
     nav.toggleCurrent = function (elem) {
         var parent_li = elem.closest('li');
-        parent_li.siblings('li.current').removeClass('current');
-        parent_li.siblings().find('li.current').removeClass('current');
+        parent_li
+            .siblings('li.current')
+            .removeClass('current')
+            .attr('aria-expanded','false');
+        parent_li
+            .siblings()
+            .find('li.current')
+            .removeClass('current')
+            .attr('aria-expanded','false');
         var children = parent_li.find('> ul li');
         // Don't toggle terminal elements.
         if (children.length) {
-            children.removeClass('current');
-            parent_li.toggleClass('current');
+            children
+                .removeClass('current')
+                .attr('aria-expanded','false');
+            parent_li
+                .toggleClass('current')
+                .attr('aria-expanded', function(i, old) {
+                    return old == 'true' ? 'false' : 'true';
+                });
         }
     }