Support mkdocs 1.4.2 and fix its missing breadcrumb (#1691)

* Use latest mkdocs version 1.4.2
* Add docs_theme to mkdocs watch so it automatically reloads localhost when modifying theme
* Bring in ReadTheDocs breadcrumb theme and fix display issues around "Docs" root breadcrumb
* The problem is CSS, not the breadcrumbs template. Tightly scope offending CSS and remove breadcrumbs template override
* Bring mkdocs ReadTheDocs breadcrumbs theme back in
* Fix pa11y validation issue by replacing breadcrumb a alt attribute with aria-label
* Attribute source of new breadcrumbs file
* Use mkdocs 1.4 or greater with no upper bound

docs_theme/assets/theme.css

@@ -118,7 +118,7 @@ div.rst-content {
   background-size: 100%;
 }
 
-a.icon-home:before {
+.wy-side-nav-search a.icon-home:before {
   display: block;
   width: 84px;
   height: 70px;

docs_theme/breadcrumbs.html

@@ -0,0 +1,49 @@
+<!--
+Copied from https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/readthedocs/breadcrumbs.html
+Then lightly modified for accessibility
+-->
+
+<div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="{{ nav.homepage.url|url }}" class="icon icon-home" aria-label="{% trans %}Docs{% endtrans %}"></a> &raquo;</li>
+    {%- if page %}
+      {%- for doc in page.ancestors[::-1] %}
+        {%- if doc.link %}
+          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+        {%- else %}
+          <li>{{ doc.title }} &raquo;</li>
+        {%- endif %}
+      {%- endfor %}
+      <li>{{ page.title }}</li>
+    {%- endif %}
+    <li class="wy-breadcrumbs-aside">
+      {%- block repo %}
+      {%- if page and page.edit_url %}
+        {%- if config.repo_name|lower == 'github' %}
+          <a href="{{ page.edit_url }}" class="icon icon-github"> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}</a>
+        {%- elif config.repo_name|lower == 'bitbucket' %}
+          <a href="{{ page.edit_url }}" class="icon icon-bitbucket"> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}</a>
+        {%- elif config.repo_name|lower == 'gitlab' %}
+          <a href="{{ page.edit_url }}" class="icon icon-gitlab"> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}</a>
+        {%- elif config.repo_name %}
+          <a href="{{ page.edit_url }}">{% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}</a>
+        {%- else %}
+          <a href="{{ page.edit_url }}">{% trans %}Edit{% endtrans %}</a>
+        {%- endif %}
+      {%- endif %}
+      {%- endblock %}
+    </li>
+  </ul>
+  {%- if config.theme.prev_next_buttons_location|lower in ['top', 'both']
+        and page and (page.next_page or page.previous_page) %}
+    <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="{% trans %}Breadcrumb Navigation{% endtrans %}">
+      {%- if page.previous_page %}
+        <a href="{{ page.previous_page.url|url }}" class="btn btn-neutral float-left" title="{{ page.previous_page.title }}"><span class="icon icon-circle-arrow-left" aria-hidden="true"></span> {% trans %}Previous{% endtrans %}</a>
+      {%- endif %}
+      {%- if page.next_page %}
+        <a href="{{ page.next_page.url|url }}" class="btn btn-neutral float-right" title="{{ page.next_page.title }}">{% trans %}Next{% endtrans %} <span class="icon icon-circle-arrow-right" aria-hidden="true"></span></a>
+      {%- endif %}
+    </div>
+  {%- endif %}
+  <hr/>
+</div>

docs_theme/requirements.txt

@@ -1,2 +1,2 @@
-mkdocs==1.2.4
+mkdocs>=1.4
 jinja2==3.1.2

mkdocs.yml

@@ -5,6 +5,9 @@ theme:
   custom_dir: docs_theme
   static_templates:
       - index.html
+watch:
+  - docs
+  - docs_theme
 extra_css:
     - https://fonts.googleapis.com/css?family=Open+Sans:300,600
     - assets/colors.css

pyproject.toml

@@ -51,7 +51,7 @@ flake8-type-checking = ">=2.2.0"
 flake8-simplify = ">=0.19"
 ipdb = "*"
 isort = ">=5.10"
-mkdocs = ">=1.0,<1.3"
+mkdocs = ">=1.4"
 poethepoet = "*"
 pytest = ">=6.2"
 pytest-bdd = ">=4.0.1,<6.0"