Continued improvements of documentation stylings (#4742)

docs/source/conf.py

@@ -228,7 +228,10 @@ html_theme_options = {
     'repo_name': 'GitHub',
 
     # Visible levels of the global TOC; -1 means unlimited
-    'globaltoc_depth': 3,
+    'globaltoc_depth': 5,
+
+    # Expand all toc so that they can be dynamically collapsed
+    'globaltoc_collapse': False,
 
     'version_dropdown': True,
     # This is a placeholder, which should be replaced later.

docs/static/css/material_custom.css

-/* Material icon: https://developers.google.com/fonts/docs/material_icons */
-/* Icon library: https://fonts.google.com/icons */
-.material-icons {
-    font-family: 'Material Icons';
-    font-weight: normal;
-    font-style: normal;
-    font-size: 24px;  /* Preferred icon size */
-    display: inline-block;
-    line-height: 1;
-    text-transform: none;
-    letter-spacing: normal;
-    word-wrap: normal;
-    white-space: nowrap;
-    direction: ltr;
-
-    /* Support for all WebKit browsers. */
-    -webkit-font-smoothing: antialiased;
-    /* Support for Safari and Chrome. */
-    text-rendering: optimizeLegibility;
-
-    /* Support for Firefox. */
-    -moz-osx-font-smoothing: grayscale;
-
-    /* Support for IE. */
-    font-feature-settings: 'liga';
-}
-
 /* Global font */
 body, input {
     font-family: "Roboto", "Noto Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
@@ -59,23 +32,23 @@ dt.sig-object {
     position: relative;
     background: #f4f5f7;
     padding: 0.5rem;
-    border-left: 0.2rem solid var(--custom-color-accent);  /* this should be matched with theme color. */
+    border-left: 0.2rem solid var(--custom-color-accent);
     word-wrap: break-word;
 }
 
 .class > dt.sig-object {
     border-left: none;                    /* remove left border */
-    border-top: 0.18rem solid var(--custom-color-accent);  /* this should be matched with theme color. */
+    border-top: 0.18rem solid var(--custom-color-accent);
 }
 
 .function > dt.sig-object {
     border-left: none;                    /* remove left border */
-    border-top: 0.18rem solid var(--custom-color-accent);  /* this should be matched with theme color. */
+    border-top: 0.18rem solid var(--custom-color-accent);
 }
 
 .exception > dt.sig-object {
     border-left: none;                    /* remove left border */
-    border-top: 0.18rem solid var(--custom-color-accent);  /* this should be matched with theme color. */
+    border-top: 0.18rem solid var(--custom-color-accent);
 }
 
 /* Padding on parameter list is not needed */
@@ -88,7 +61,7 @@ dl.field-list > dd {
 }
 
 /* show headerlink when hover/focus */
-.headerlink:focus, .headerlink:hover {
+dt.sig-object:focus .headerlink, dt.sig-object:hover .headerlink {
     -webkit-transform: translate(0);
     transform: translate(0);
     opacity: 1;
@@ -99,15 +72,15 @@ a.md-logo img {
     padding: 3px;
 }
 
-/* Add split for navigation */
+/* Split for navigation */
 nav.md-tabs .md-tabs__item:not(:last-child) {
     padding-right: 0;
 }
 
-nav.md-tabs .md-tabs__item:not(:last-child) .md-tabs__link:after {
-    content: "»";
-    font-family: "Material Icons";
-    padding-left: 0.6rem;
+nav.md-tabs .md-tabs__arrow {
+    padding-left: .3rem;
+    font-size: inherit;
+    vertical-align: -10%;
 }
 
 /* hide the floating button generated by readthedocs */
@@ -289,6 +262,9 @@ dt:target {
     .md-nav--primary .md-nav__link {
         padding: .15rem .5rem;
     }
+    .md-nav--primary .md-nav__tocarrow {
+        display: none;
+    }
     .md-nav--primary span.md-nav__link.caption {
         margin-top: 0.75em;
     }
@@ -303,6 +279,39 @@ dt:target {
         padding-top: 2rem;
         height: 4.6rem;
     }
+    .md-nav__expand .md-nav__list {
+        display: block;
+    }
+}
+
+/* collapsible toctree */
+.md-nav--primary ul li {
+    padding-left: .8rem;
+}
+
+.md-nav__item {
+    position: relative;
+}
+
+.md-nav__expand > a > .md-nav__tocarrow {
+    transform: rotate(-90deg);
+    font-size: inherit;
+    transition: all 0.1s ease;
+    position: absolute;
+    left: .1rem;
+    top: .05rem;
+}
+
+.md-nav__expand .md-nav__list {
+    display: none;
+}
+
+.md-nav__expand--active > .md-nav__list {
+    display: block;
+}
+
+.md-nav__expand--active > a > .md-nav__tocarrow {
+    transform: rotate(0);
 }
 
 /* Increase TOC padding */

docs/static/css/sphinx_gallery.css

@@ -26,6 +26,7 @@ div.sphx-glr-footer {
 
 .sphx-glr-download-link-note {
     margin-bottom: 1.5rem;
+    line-height: 2.5rem;
 }
 
 .notebook-action-div {

docs/static/js/misc.js

@@ -42,6 +42,33 @@ function hide_nav() {
     }
 }
 
+// Expand link
+function expand_link() {
+    // on load, collapse all links without active on the inside
+    $(".md-nav__expand").filter(function (index) {
+        return $(".md-nav__link--active", this).length >= 1;
+    }).addClass("md-nav__expand--active");
+
+    // bind click events
+    $(".md-nav__expand > a").click(function (e) {
+        if (window.matchMedia("only screen and (min-width: 76.2em)").matches) {
+            // not a drawer
+            e.preventDefault();
+            
+            const target = $(e.target).parent();
+            if (target.hasClass("md-nav__expand--active")) {
+                target.removeClass("md-nav__expand--active");
+            } else {
+                target.addClass("md-nav__expand--active");
+            }
+
+            return false;
+        }
+        return true;
+    });
+}
+
 $(document).ready(function() {
     hide_nav();
+    expand_link();
 });

docs/templates/globaltoc.html

@@ -6,7 +6,7 @@
       <a href="{{ pathto('index')|e }}" class="md-nav__link{% if pagename == 'index' %} md-nav__link--active{% endif %}">{{ _('Overview') }}</a>
     </li>
   {%- for item in toctree_nodes recursive %}
-    <li class="md-nav__item">
+    <li class="md-nav__item{% if item.children %} md-nav__expand{% endif %}">
     {% if "caption" in item %}
       <span class="md-nav__link caption">{{ item.caption }}</span>
     {% else %}
@@ -14,7 +14,12 @@
     <input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
     <label class="md-nav__link md-nav__link--active" for="__toc"> {{ item.contents }} </label>
     {% endif %}
-      <a href="{{ item.href|e }}" class="md-nav__link{% if item.current %} md-nav__link--active{% endif %}">{{ item.contents }}</a>
+      <a href="{{ item.href|e }}" class="md-nav__link{% if item.current %} md-nav__link--active{% endif %}">
+      {% if item.children %}
+        <span class="material-icons md-nav__tocarrow">&#xE5C5;</span>
+      {% endif %}
+      {{ item.contents }}
+      </a>
       {% if item.current %}
         {%- set sphinx_material_include_searchbox=False %}
         {% include "localtoc.html" %}

docs/templates/layout.html

@@ -3,7 +3,7 @@
 {#- SPECIFY PARTICULAR FONTS FOR HEADERS #}
 {% block font %}
   <link href="https://fonts.gstatic.com/" rel="preconnect" crossorigin>
-  <link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,500,700|Roboto:400,400i,500,700|Google+Sans:400,500,600&display=fallback" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,500,700|Roboto:400,400i,500,700|Google+Sans:400,500,600|Material+Icons&display=fallback" rel="stylesheet">
 {% endblock %}
 
 {#- TO INJECT INFORMATION FROM READTHEDOCS HERE #}

docs/templates/relbar.html

+{%- if nav_bar_tabs and (parents or theme_nav_links) %}
+  <nav class="md-tabs" data-md-component="tabs">
+    <div class="md-tabs__inner md-grid">
+      <ul class="md-tabs__list">
+        {%- block rootrellink %}
+          {%- if theme_master_doc %}
+          <li class="md-tabs__item">
+            <a href="{{ pathto(master_doc)|e }}" class="md-tabs__link">
+              {{ shorttitle }}
+              <span class="material-icons md-tabs__arrow">&#xEAC9;</span>
+            </a>
+          </li>
+          {%- endif %}
+        {%- endblock %}
+        {#- DO NOT SUPPORT THEME NAV LINKS HERE #}
+        {%- for parent in parents %}
+          <li class="md-tabs__item">
+            <a href="{{ parent.link|e }}" class="md-tabs__link">
+              {{ parent.title }}
+              <span class="material-icons md-tabs__arrow">&#xEAC9;</span>
+            </a>
+          </li>
+        {%- endfor %}
+        <li class="md-tabs__item"><a href="#" class="md-tabs__link">{{ title|striptags|e }}</a></li>
+      </ul>
+    </div>
+  </nav>
+{%- endif %}