add version select capability for v2.0 (main branch)

docs/theme_overrides/assets/javascripts/version-select.js

@@ -0,0 +1,45 @@
+document.addEventListener('DOMContentLoaded', () => {
+    const verSelDom = document.querySelector('#version-select')
+    const verSelListDom = verSelDom.querySelector('.mdc-list')
+
+    const baseURL = verSelDom.dataset.baseUrl
+    const absBaseURL = new URL(baseURL, window.location.href)
+    var curDocVer = absBaseURL.pathname.match(/([^\/]*)\/?$/)[1]
+    curDocVer = curDocVer || "latest"
+
+    function updateVersionSelectDOM(verItems) {
+        verItems.forEach((verItem) => {
+            var rippleSpan = document.createElement('span')
+            rippleSpan.classList.add("mdc-list-item__ripple")
+            var textSpan = document.createElement('span')
+            textSpan.classList.add("mdc-list-item__text")
+            textSpan.innerHTML = verItem.title
+
+            var verSelListItem = document.createElement('li');
+            verSelListItem.setAttribute("role", "option")
+            verSelListItem.setAttribute("data-value", verItem.version)
+            verSelListItem.classList.add("mdc-list-item")
+            if (verItem.version == curDocVer || verItem.aliases.includes(curDocVer)) {
+                verSelListItem.classList.add("mdc-list-item--selected")
+            }
+            verSelListItem.appendChild(rippleSpan)
+            verSelListItem.appendChild(textSpan)
+            verSelListDom.appendChild(verSelListItem)
+        })
+    }
+
+    function setupVersionSelectEventHandlers() {
+        const verSelMDC = new mdc.select.MDCSelect(verSelDom);
+        verSelMDC.listen('MDCSelect:change', () => {
+            const chosenDocVer = verSelMDC.value
+            const chosenDocURL = new URL("../" + chosenDocVer, absBaseURL)
+            window.location.href = chosenDocURL
+        });
+    }
+
+    const verJSONURL = new URL(baseURL + "/../versions.json", window.location.href)
+    fetch(verJSONURL)
+        .then(response => response.json())
+        .then(updateVersionSelectDOM)
+        .then(setupVersionSelectEventHandlers)
+});

docs/theme_overrides/assets/stylesheets/version-select.css

@@ -0,0 +1,12 @@
+#version-select .mdc-select__anchor {
+    display: flex;
+    align-items: center;
+}
+
+#version-select {
+    width: 120px;
+}
+
+#version-select .mdc-select__selected-text {
+    color: var(--md-primary-bg-color)
+}

docs/theme_overrides/main.html

@@ -0,0 +1,11 @@
+{% extends "base.html" %}
+
+{% block styles %}
+    {{ super() }}
+    <link rel="stylesheet" href="{{ 'assets/stylesheets/version-select.css' | url }}">
+{% endblock %}
+
+{% block scripts %}
+    {{ super() }}
+    <script src="{{ 'assets/javascripts/version-select.js' | url }}"></script>
+{% endblock %}

docs/theme_overrides/partials/header.html

@@ -0,0 +1,47 @@
+{% set site_url = config.site_url | default(nav.homepage.url, true) | url %}
+{% if not config.use_directory_urls and site_url[0] == site_url[-1] == "." %}
+{% set site_url = site_url ~ "/index.html" %}
+{% endif %}
+<header class="md-header" data-md-component="header">
+    <nav class="md-header-nav md-grid" aria-label="{{ lang.t('header.title') }}">
+        <a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header-nav__button md-logo"
+            aria-label="{{ config.site_name }}">
+            {% include "partials/logo.html" %}
+        </a>
+        <label class="md-header-nav__button md-icon" for="__drawer">
+            {% include ".icons/material/menu" ~ ".svg" %}
+        </label>
+        <div class="md-header-nav__title" data-md-component="header-title">
+            {% if config.site_name == page.title %}
+            <div class="md-header-nav__ellipsis md-ellipsis">
+                {{ config.site_name }}
+            </div>
+            {% else %}
+            <div class="md-header-nav__ellipsis">
+                <span class="md-header-nav__topic md-ellipsis">
+                    {{ config.site_name }}
+                </span>
+                <span class="md-header-nav__topic md-ellipsis">
+                    {% if page and page.meta and page.meta.title %}
+                    {{ page.meta.title }}
+                    {% else %}
+                    {{ page.title }}
+                    {% endif %}
+                </span>
+            </div>
+            {% endif %}
+        </div>
+        {% include "partials/version-select.html" %}
+        {% if "search" in config["plugins"] %}
+        <label class="md-header-nav__button md-icon" for="__search">
+            {% include ".icons/material/magnify.svg" %}
+        </label>
+        {% include "partials/search.html" %}
+        {% endif %}
+        {% if config.repo_url %}
+        <div class="md-header-nav__source">
+            {% include "partials/source.html" %}
+        </div>
+        {% endif %}
+    </nav>
+</header>

docs/theme_overrides/partials/version-select.html

@@ -0,0 +1,23 @@
+<div id="version-select" class="mdc-select" data-base-url="{{ base_url }}">
+    <div class="mdc-select__anchor" role="button">
+        <span class="mdc-select__ripple"></span>
+        <span class="mdc-select__selected-text-container">
+            <span class="mdc-select__selected-text"></span>
+        </span>
+        <span class="mdc-select__dropdown-icon">
+            <svg class="mdc-select__dropdown-icon-graphic" viewBox="7 10 10 5" focusable="false">
+                <polygon class="mdc-select__dropdown-icon-inactive" stroke="none" fill-rule="evenodd"
+                    points="7 10 12 15 17 10">
+                </polygon>
+                <polygon class="mdc-select__dropdown-icon-active" stroke="none" fill-rule="evenodd"
+                    points="7 15 12 10 17 15">
+                </polygon>
+            </svg>
+        </span>
+    </div>
+
+    <div class="mdc-select__menu mdc-menu mdc-menu-surface mdc-menu-surface--fullwidth">
+        <ul class="mdc-list" role="listbox">
+        </ul>
+    </div>
+</div>

mkdocs.yml

@@ -42,6 +42,7 @@ theme:
     code: Roboto Mono
   features:
     - tabs
+  custom_dir: docs/theme_overrides
 # Extensions
 markdown_extensions:
   - admonition
@@ -53,3 +54,7 @@ markdown_extensions:
   - pymdownx.tabbed
   - toc:
       permalink: true
+extra_css:
+  - https://unpkg.com/material-components-web@latest/dist/material-components-web.min.css
+extra_javascript:
+  - https://unpkg.com/material-components-web@latest/dist/material-components-web.min.js