docs: Updated RTD to 2.0.0 and removed dependency on jQuery. (#12253)

mamedev · Apr 15, 2024 · 7542e0a · 7542e0a
1 parent c4f79f1
commit 7542e0a
Show file tree

Hide file tree

Showing 51 changed files with 877 additions and 309 deletions.
diff --git a/docs/source/_templates/versions.html b/docs/source/_templates/versions.html
@@ -1,14 +1,7 @@
 {% if mamedev_site %}
     <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Downloads') }}">
-        <span class="rst-current-version" data-toggle="rst-current-version">
-            <span class="fa fa-book">Downloads</span>
-            <span class="fa fa-caret-down"></span>
-        </span>
-        <div class="rst-other-versions">
-            <dl>
-                <dd><a href="https://docs.mamedev.org/_files/MAME.pdf">PDF</a></dd>
-                <dd><a href="https://docs.mamedev.org/_files/MAME.epub">EPUB</a></dd>
-            </dl>
-        </div>
+		<span class="rst-current-version" data-toggle="rst-current-version">
+			Download documentation as <a href="https://docs.mamedev.org/_files/MAME.pdf">PDF</a> or <a href="https://docs.mamedev.org/_files/MAME.epub">EPUB</a>
+		</span>
     </div>
 {% endif %}
diff --git a/docs/themes/sphinx_rtd_theme/__init__.py b/docs/themes/sphinx_rtd_theme/__init__.py
@@ -12,7 +12,7 @@
 from sphinx.util.logging import getLogger
 
 
-__version__ = '1.0.0rc1'
+__version__ = '2.0.0'
 __version_full__ = __version__
 
 logger = getLogger(__name__)
@@ -31,33 +31,47 @@ def config_initiated(app, config):
             _('The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead.')
         )
 
+
+def extend_html_context(app, pagename, templatename, context, doctree):
+     # Add ``sphinx_version_info`` tuple for use in Jinja templates
+     context['sphinx_version_info'] = sphinx_version
+
+
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
     if python_version[0] < 3:
-        logger.warning("Python 2 is deprecated with sphinx_rtd_theme, update to Python 3")
-    app.require_sphinx('1.6')
-    if sphinx_version <= (2, 0, 0):
-        logger.warning("Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater")
-        if not app.config.html_experimental_html5_writer:
-            logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")
-    else:
-        if app.config.html4_writer:
-            logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")
+        logger.error("Python 2 is not supported with sphinx_rtd_theme, update to Python 3.")
+
+    app.require_sphinx('5.0')
+    if app.config.html4_writer:
+        logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")
+
+    # Since Sphinx 6, jquery isn't bundled anymore and we need to ensure that
+    # the sphinxcontrib-jquery extension is enabled.
+    # See: https://dev.readthedocs.io/en/latest/design/sphinx-jquery.html
+    if sphinx_version >= (6, 0, 0):
+        # Documentation of Sphinx guarantees that an extension is added and
+        # enabled at most once.
+        # See: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.setup_extension
+        app.setup_extension("sphinxcontrib.jquery")
+        # However, we need to call the extension's callback since setup_extension doesn't do it
+        # See: https://github.com/sphinx-contrib/jquery/issues/23
+        from sphinxcontrib.jquery import add_js_files as jquery_add_js_files
+        jquery_add_js_files(app, app.config)
 
     # Register the theme that can be referenced without adding a theme path
     app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))
 
-    if sphinx_version >= (1, 8, 0):
-        # Add Sphinx message catalog for newer versions of Sphinx
-        # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
-        rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
-        app.add_message_catalog('sphinx', rtd_locale_path)
-        app.connect('config-inited', config_initiated)
+    # Add Sphinx message catalog for newer versions of Sphinx
+    # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
+    rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
+    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"
+    app.config.html_permalinks_icon = "\uf0c1"
+
+    # Extend the default context when rendering the templates.
+    app.connect("html-page-context", extend_html_context)
 
     return {'parallel_read_safe': True, 'parallel_write_safe': True}
diff --git a/docs/themes/sphinx_rtd_theme/breadcrumbs.html b/docs/themes/sphinx_rtd_theme/breadcrumbs.html
@@ -22,11 +22,11 @@
 <div role="navigation" aria-label="{{ _('Page navigation') }}">
   <ul class="wy-breadcrumbs">
     {%- block breadcrumbs %}
-      <li><a href="{{ pathto(master_doc) }}" class="icon icon-home"></a> &raquo;</li>
+      <li><a href="{{ pathto(master_doc) }}" class="icon icon-home" aria-label="Home"></a></li>
         {%- for doc in parents %}
-          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+          <li class="breadcrumb-item"><a href="{{ doc.link|e }}">{{ doc.title }}</a></li>
         {%- endfor %}
-      <li>{{ title }}</li>
+      <li class="breadcrumb-item active">{{ title }}</li>
     {%- endblock %}
     {%- block breadcrumbs_aside %}
       <li class="wy-breadcrumbs-aside">

diff --git a/docs/themes/sphinx_rtd_theme/footer.html b/docs/themes/sphinx_rtd_theme/footer.html
@@ -51,7 +51,7 @@
     {%- set readthedocs_web = '<a href="https://readthedocs.org">Read the Docs</a>'  %}
     {#- Translators: the variable "sphinx_web" is a link to the Sphinx project documentation with the text "Sphinx" #}
     {%- trans sphinx_web=sphinx_web, readthedocs_web=readthedocs_web %}Built with {{ sphinx_web }} using a{% endtrans %}
-    {#- Translators: "theme" refers to a theme for Sphinx, which alters the appearance of the generated documenation #}
+    {#- Translators: "theme" refers to a theme for Sphinx, which alters the appearance of the generated documentation #}
     <a href="https://github.com/readthedocs/sphinx_rtd_theme">{% trans %}theme{% endtrans %}</a>
     {#- Translators: this is always used as "provided by Read the Docs", and should not imply Read the Docs is an author of the generated documentation. #}
     {% trans %}provided by {{ readthedocs_web }}{% endtrans %}.

diff --git a/docs/themes/sphinx_rtd_theme/layout.html b/docs/themes/sphinx_rtd_theme/layout.html
@@ -10,11 +10,11 @@
 {%- set sphinx_writer = 'writer-html5' if html5_doctype else 'writer-html4' -%}
 
 {# Build sphinx_version_info tuple from sphinx_version string in pure Jinja #}
-{%- set (_ver_major, _ver_minor, _ver_bugfix) = sphinx_version.split('.') | map('int') -%}
-{%- set sphinx_version_info = (_ver_major, _ver_minor, _ver_bugfix) -%}
+{%- set (_ver_major, _ver_minor) = (sphinx_version.split('.') | list)[:2] | map('int') -%}
+{%- set sphinx_version_info = (_ver_major, _ver_minor, -1) -%}
 
 <!DOCTYPE html>
-<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
+<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
 <head>
   <meta charset="utf-8" />
   {{- metatags }}
@@ -28,26 +28,27 @@
     <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
     <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
   {%- endif %}
-  {%- for css in css_files %}
-    {%- if css|attr("rel") %}
-      <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
+  {%- for css_file in css_files %}
+    {%- if css_file|attr("filename") %}
+      {{ css_tag(css_file) }}
     {%- else %}
-      <link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
+      <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
     {%- endif %}
   {%- endfor %}
 
-  {%- for cssfile in extra_css_files %}
-    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {# "extra_css_files" is a theme option and it's always a string #}
+  {%- for css_file in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
   {%- endfor -%}
 
-  {#- FAVICON #}
-  {%- if favicon %}
-    {%- if sphinx_version_info < (4, 0) -%}
-    <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
-    {%- else %}
-    <link rel="shortcut icon" href="{{ favicon_url }}"/>
-    {%- endif %}
-  {%- endif -%}
+  {#- FAVICON
+      favicon_url is the only context var necessary since Sphinx 4.
+      In Sphinx<4, we use favicon but need to prepend path info.
+  #}
+  {%- set _favicon_url = favicon_url | default(pathto('_static/' + (favicon or ""), 1)) %}
+  {%- if favicon_url or favicon %}
+    <link rel="shortcut icon" href="{{ _favicon_url }}"/>
+  {%- endif %}
 
   {#- CANONICAL URL (deprecated) #}
   {%- if theme_canonical_url and not pageurl %}
@@ -133,22 +134,15 @@
         <div class="wy-side-nav-search" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>
           {%- block sidebartitle %}
 
-          {%- if logo and theme_logo_only %}
-            <a href="{{ pathto(master_doc) }}">
-          {%- else %}
-            <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
-          {%- endif %}
-
-          {%- if logo %}
-            {#- Not strictly valid HTML, but it's the only way to display/scale
-                it properly, without weird scripting or heaps of work
-            #}
-            {%- if sphinx_version_info < (4, 0) -%}
-            <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
-            {%- else %}
-            <img src="{{ logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
+          {# 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 %} class="icon icon-home"{% endif %}>
+            {% if not theme_logo_only %}{{ project }}{% endif %}
+            {%- if logo or logo_url %}
+              <img src="{{ _logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
             {%- endif %}
-          {%- endif %}
           </a>
 
           {%- if theme_display_version %}

diff --git a/docs/themes/sphinx_rtd_theme/locale/da/LC_MESSAGES/sphinx.mo b/docs/themes/sphinx_rtd_theme/locale/da/LC_MESSAGES/sphinx.mo