Unpin sphinx_rtd_theme and add a workaround for sphinx_rtd_theme v3.0 (#3892)

Author: seisman

.github/workflows/ci_docs.yml

@@ -114,7 +114,7 @@ jobs:
             sphinx-copybutton
             sphinx-design
             sphinx-gallery
-            sphinx_rtd_theme<3.0
+            sphinx_rtd_theme
             cairosvg
             sphinxcontrib-svg2pdfconverter
             tectonic

ci/requirements/docs.yml

@@ -31,7 +31,7 @@ dependencies:
     - sphinx-copybutton
     - sphinx-design
     - sphinx-gallery
-    - sphinx_rtd_theme<3.0
+    - sphinx_rtd_theme
     # Dev dependencies (building PDF documentation)
     # 'sphinxcontrib-svg2pdfconverter' is required since it's added to `extensions`.
     - sphinxcontrib-svg2pdfconverter

doc/_static/style.css

@@ -52,6 +52,15 @@ p {
     max-width: 1000px;
 }
 
+/* Compatibility with sphinx_rtd_theme v3.x.x */
+/* https://github.com/TexasInstruments/processor-sdk-doc/commit/4fa6276ddcf7f9db919af2e5b3aec7e70a1afa16 */
+.wy-side-nav-search>div.version {
+    margin-top: -.4045em;
+    margin-bottom: .809em;
+    font-weight: 400;
+    color: hsla(0, 0%, 100%, .3);
+}
+
 /* Format parameters section similar to sphinx_rtd_theme v4.x.x (not a grid) */
 html.writer-html5 .rst-content dl.field-list {
     display: initial;

doc/_templates/layout.html

@@ -31,24 +31,25 @@
 {% endblock %}
 
 
-{% block sidebartitle %}
-    <a href="{{ pathto(root_doc) }}"><h2 class="sidebar-title">{{ project }}</h2></a>
-
-    {% if theme_display_version %}
-        {%- set nav_version = version %}
-        {% if READTHEDOCS and current_version %}
-            {%- set nav_version = current_version %}
-        {% endif %}
-        {% if nav_version %}
-            <div class="version">
-                {{ nav_version }}
-            </div>
-        {% endif %}
-    {% endif %}
-
-    {% include "searchbox.html" %}
-
-{% endblock %}
+{%- block sidebartitle %}
+   {# the logo helper function was removed in Sphinx 6 and deprecated since Sphinx 4 #}
+   {# the master_doc variable was renamed to root_doc in Sphinx 4 (master_doc still exists in later Sphinx versions) #}
+   {%- set _logo_url = logo_url|default(pathto('_static/' + (logo or ""), 1)) %}
+   {%- set _root_doc = root_doc|default(master_doc) %}
+   <a href="{{ pathto(_root_doc) }}">
+     {% if not theme_logo_only %}<h2 class="sidebar-title">{{ project }}</h2>{% endif %}
+     {%- if logo or logo_url %}
+       <img src="{{ _logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
+     {%- endif %}
+   </a>
+   {%- set nav_version = version %}
+   {%- if nav_version %}
+     <div class="version">
+       {{ nav_version }}
+     </div>
+   {%- endif %}
+   {%- include "searchbox.html" %}
+ {% endblock %}
 
 
 {% block menu %}

environment.yml

@@ -43,7 +43,7 @@ dependencies:
     - sphinx-copybutton
     - sphinx-design
     - sphinx-gallery>=0.19.0
-    - sphinx_rtd_theme<3.0
+    - sphinx_rtd_theme
     # Dev dependencies (building PDF documentation)
     - cairosvg
     - sphinxcontrib-svg2pdfconverter