Skip to content

Commit b1c5978

Browse files
FirehawkeFirehawke
committed
Update RTD theme for docs to 2.0.0, minor template workaround
1 parent bbfee2d commit b1c5978

File tree

25 files changed

+442
-336
lines changed

25 files changed

+442
-336
lines changed

‎docs/source/_templates/versions.html

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,7 @@
11
{% if mamedev_site %}
22
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Downloads') }}">
3-
<span class="rst-current-version" data-toggle="rst-current-version">
4-
<span class="fa fa-book">Downloads</span>
5-
<span class="fa fa-caret-down"></span>
6-
</span>
7-
<div class="rst-other-versions">
8-
<dl>
9-
<dd><a href="https://docs.mamedev.org/_files/MAME.pdf">PDF</a></dd>
10-
<dd><a href="https://docs.mamedev.org/_files/MAME.epub">EPUB</a></dd>
11-
</dl>
12-
</div>
3+
<span class="rst-current-version" data-toggle="rst-current-version">
4+
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>
5+
</span>
136
</div>
147
{% endif %}

‎docs/themes/sphinx_rtd_theme/__init__.py

Lines changed: 34 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
from sphinx.util.logging import getLogger
1313

1414

15-
__version__ = '1.0.0rc1'
15+
__version__ = '2.0.1alpha1'
1616
__version_full__ = __version__
1717

1818
logger = getLogger(__name__)
@@ -31,33 +31,47 @@ def config_initiated(app, config):
3131
_('The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead.')
3232
)
3333

34+
35+
def extend_html_context(app, pagename, templatename, context, doctree):
36+
# Add ``sphinx_version_info`` tuple for use in Jinja templates
37+
context['sphinx_version_info'] = sphinx_version
38+
39+
3440
# See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
3541
def setup(app):
3642
if python_version[0] < 3:
37-
logger.warning("Python 2 is deprecated with sphinx_rtd_theme, update to Python 3")
38-
app.require_sphinx('1.6')
39-
if sphinx_version <= (2, 0, 0):
40-
logger.warning("Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater")
41-
if not app.config.html_experimental_html5_writer:
42-
logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")
43-
else:
44-
if app.config.html4_writer:
45-
logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")
43+
logger.error("Python 2 is not supported with sphinx_rtd_theme, update to Python 3.")
44+
45+
app.require_sphinx('5.0')
46+
if app.config.html4_writer:
47+
logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")
48+
49+
# Since Sphinx 6, jquery isn't bundled anymore and we need to ensure that
50+
# the sphinxcontrib-jquery extension is enabled.
51+
# See: https://dev.readthedocs.io/en/latest/design/sphinx-jquery.html
52+
if sphinx_version >= (6, 0, 0):
53+
# Documentation of Sphinx guarantees that an extension is added and
54+
# enabled at most once.
55+
# See: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.setup_extension
56+
app.setup_extension("sphinxcontrib.jquery")
57+
# However, we need to call the extension's callback since setup_extension doesn't do it
58+
# See: https://github.com/sphinx-contrib/jquery/issues/23
59+
from sphinxcontrib.jquery import add_js_files as jquery_add_js_files
60+
jquery_add_js_files(app, app.config)
4661

4762
# Register the theme that can be referenced without adding a theme path
4863
app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))
4964

50-
if sphinx_version >= (1, 8, 0):
51-
# Add Sphinx message catalog for newer versions of Sphinx
52-
# See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
53-
rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
54-
app.add_message_catalog('sphinx', rtd_locale_path)
55-
app.connect('config-inited', config_initiated)
65+
# Add Sphinx message catalog for newer versions of Sphinx
66+
# See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
67+
rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
68+
app.add_message_catalog('sphinx', rtd_locale_path)
69+
app.connect('config-inited', config_initiated)
5670

5771
# sphinx emits the permalink icon for headers, so choose one more in keeping with our theme
58-
if sphinx_version >= (3, 5, 0):
59-
app.config.html_permalinks_icon = "\uf0c1"
60-
else:
61-
app.config.html_add_permalinks = "\uf0c1"
72+
app.config.html_permalinks_icon = "\uf0c1"
73+
74+
# Extend the default context when rendering the templates.
75+
app.connect("html-page-context", extend_html_context)
6276

6377
return {'parallel_read_safe': True, 'parallel_write_safe': True}

‎docs/themes/sphinx_rtd_theme/breadcrumbs.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,11 @@
2222
<div role="navigation" aria-label="{{ _('Page navigation') }}">
2323
<ul class="wy-breadcrumbs">
2424
{%- block breadcrumbs %}
25-
<li><a href="{{ pathto(master_doc) }}" class="icon icon-home"></a> &raquo;</li>
25+
<li><a href="{{ pathto(master_doc) }}" class="icon icon-home" aria-label="Home"></a></li>
2626
{%- for doc in parents %}
27-
<li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
27+
<li class="breadcrumb-item"><a href="{{ doc.link|e }}">{{ doc.title }}</a></li>
2828
{%- endfor %}
29-
<li>{{ title }}</li>
29+
<li class="breadcrumb-item active">{{ title }}</li>
3030
{%- endblock %}
3131
{%- block breadcrumbs_aside %}
3232
<li class="wy-breadcrumbs-aside">

‎docs/themes/sphinx_rtd_theme/footer.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
{%- set readthedocs_web = '<a href="https://readthedocs.org">Read the Docs</a>' %}
5252
{#- Translators: the variable "sphinx_web" is a link to the Sphinx project documentation with the text "Sphinx" #}
5353
{%- trans sphinx_web=sphinx_web, readthedocs_web=readthedocs_web %}Built with {{ sphinx_web }} using a{% endtrans %}
54-
{#- Translators: "theme" refers to a theme for Sphinx, which alters the appearance of the generated documenation #}
54+
{#- Translators: "theme" refers to a theme for Sphinx, which alters the appearance of the generated documentation #}
5555
<a href="https://github.com/readthedocs/sphinx_rtd_theme">{% trans %}theme{% endtrans %}</a>
5656
{#- 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. #}
5757
{% trans %}provided by {{ readthedocs_web }}{% endtrans %}.

‎docs/themes/sphinx_rtd_theme/layout.html

Lines changed: 28 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,13 @@
77
{%- set titlesuffix = "" %}
88
{%- endif %}
99
{%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %}
10-
{%- set sphinx_writer = 'writer-html5' if html5_doctype else 'writer-html4' -%}
1110

1211
{# Build sphinx_version_info tuple from sphinx_version string in pure Jinja #}
13-
{%- set (_ver_major, _ver_minor, _ver_bugfix) = sphinx_version.split('.') | map('int') -%}
14-
{%- set sphinx_version_info = (_ver_major, _ver_minor, _ver_bugfix) -%}
12+
{%- set (_ver_major, _ver_minor) = (sphinx_version.split('.') | list)[:2] | map('int') -%}
13+
{%- set sphinx_version_info = (_ver_major, _ver_minor, -1) -%}
1514

1615
<!DOCTYPE html>
17-
<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
16+
<html class="writer-html5" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
1817
<head>
1918
<meta charset="utf-8" />
2019
{{- metatags }}
@@ -24,30 +23,28 @@
2423
{%- endblock -%}
2524

2625
{#- CSS #}
27-
{%- if sphinx_version_info < (4, 0) -%}
28-
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
29-
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
30-
{%- endif %}
31-
{%- for css in css_files %}
32-
{%- if css|attr("rel") %}
33-
<link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
26+
{%- for css_file in css_files %}
27+
{%- if css_file|attr("filename") %}
28+
{{ css_tag(css_file) }}
3429
{%- else %}
35-
<link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
30+
<link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
3631
{%- endif %}
3732
{%- endfor %}
3833

39-
{%- for cssfile in extra_css_files %}
40-
<link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
34+
{#
35+
"extra_css_files" is an undocumented Read the Docs theme specific option.
36+
There is no need to check for ``|attr("filename")`` here because it's always a string.
37+
Note that this option should be removed in favor of regular ``html_css_files``:
38+
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files
39+
#}
40+
{%- for css_file in extra_css_files %}
41+
<link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
4142
{%- endfor -%}
4243

4344
{#- FAVICON #}
44-
{%- if favicon %}
45-
{%- if sphinx_version_info < (4, 0) -%}
46-
<link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
47-
{%- else %}
45+
{%- if favicon_url %}
4846
<link rel="shortcut icon" href="{{ favicon_url }}"/>
49-
{%- endif %}
50-
{%- endif -%}
47+
{%- endif %}
5148

5249
{#- CANONICAL URL (deprecated) #}
5350
{%- if theme_canonical_url and not pageurl %}
@@ -61,34 +58,10 @@
6158

6259
{#- JAVASCRIPTS #}
6360
{%- block scripts %}
64-
<!--[if lt IE 9]>
65-
<script src="{{ pathto('_static/js/html5shiv.min.js', 1) }}"></script>
66-
<![endif]-->
6761
{%- if not embedded %}
68-
{# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #}
69-
{%- if sphinx_version_info >= (1, 8) -%}
70-
{%- if sphinx_version_info < (4, 0) -%}
71-
<script id="documentation_options" data-url_root="{{ url_root }}" src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
72-
{%- endif -%}
73-
{%- for scriptfile in script_files %}
74-
{{ js_tag(scriptfile) }}
75-
{%- endfor %}
76-
{%- else %}
77-
<script>
78-
var DOCUMENTATION_OPTIONS = {
79-
URL_ROOT:'{{ url_root }}',
80-
VERSION:'{{ release|e }}',
81-
LANGUAGE:'{{ language }}',
82-
COLLAPSE_INDEX:false,
83-
FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
84-
HAS_SOURCE: {{ has_source|lower }},
85-
SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}'
86-
};
87-
</script>
88-
{%- for scriptfile in script_files %}
89-
<script src="{{ pathto(scriptfile, 1) }}"></script>
90-
{%- endfor %}
91-
{%- endif %}
62+
{%- for scriptfile in script_files %}
63+
{{ js_tag(scriptfile) }}
64+
{%- endfor %}
9265
<script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
9366

9467
{#- OPENSEARCH #}
@@ -133,22 +106,15 @@
133106
<div class="wy-side-nav-search" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>
134107
{%- block sidebartitle %}
135108

136-
{%- if logo and theme_logo_only %}
137-
<a href="{{ pathto(master_doc) }}">
138-
{%- else %}
139-
<a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
140-
{%- endif %}
141-
142-
{%- if logo %}
143-
{#- Not strictly valid HTML, but it's the only way to display/scale
144-
it properly, without weird scripting or heaps of work
145-
#}
146-
{%- if sphinx_version_info < (4, 0) -%}
147-
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
148-
{%- else %}
149-
<img src="{{ logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
109+
{# the logo helper function was removed in Sphinx 6 and deprecated since Sphinx 4 #}
110+
{# the master_doc variable was renamed to root_doc in Sphinx 4 (master_doc still exists in later Sphinx versions) #}
111+
{%- set _logo_url = logo_url|default(pathto('_static/' + (logo or ""), 1)) %}
112+
{%- set _root_doc = root_doc|default(master_doc) %}
113+
<a href="{{ pathto(_root_doc) }}"{% if not theme_logo_only %} class="icon icon-home"{% endif %}>
114+
{% if not theme_logo_only %}{{ project }}{% endif %}
115+
{%- if logo or logo_url %}
116+
<img src="{{ _logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
150117
{%- endif %}
151-
{%- endif %}
152118
</a>
153119

154120
{%- if theme_display_version %}

‎docs/themes/sphinx_rtd_theme/locale/de/LC_MESSAGES/sphinx.po

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,14 @@ msgid ""
1111
msgstr ""
1212
"Project-Id-Version: sphinx_rtd_theme 0.4.3.dev0\n"
1313
"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
14-
"POT-Creation-Date: 2021-08-17 10:02-0600\n"
14+
"POT-Creation-Date: 2023-02-06 15:36+0100\n"
1515
"PO-Revision-Date: 2019-07-16 21:44+0000\n"
1616
"Last-Translator: Tom Kunze <[email protected]>, 2019\n"
1717
"Language-Team: German (https://www.transifex.com/readthedocs/teams/101354/de/)\n"
1818
"MIME-Version: 1.0\n"
1919
"Content-Type: text/plain; charset=UTF-8\n"
2020
"Content-Transfer-Encoding: 8bit\n"
21-
"Generated-By: Babel 2.8.0\n"
21+
"Generated-By: Babel 2.11.0\n"
2222
"Language: de\n"
2323
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
2424

@@ -92,7 +92,7 @@ msgstr "Suche"
9292
msgid "Copyright"
9393
msgstr "Copyright"
9494

95-
#: sphinx_rtd_theme/layout.html:147 sphinx_rtd_theme/layout.html:149
95+
#: sphinx_rtd_theme/layout.html:143
9696
msgid "Logo"
9797
msgstr "Logo"
9898

@@ -134,9 +134,3 @@ msgstr "Projektübersicht"
134134
#: sphinx_rtd_theme/versions.html:29
135135
msgid "Builds"
136136
msgstr "Builds"
137-
138-
#~ msgid "Docs"
139-
#~ msgstr "Dokumentation"
140-
141-
#~ msgid "Free document hosting provided by"
142-
#~ msgstr "Kostenloses Dokumentationen-Hosting zur Verfügung gestellt von"

‎docs/themes/sphinx_rtd_theme/locale/en/LC_MESSAGES/sphinx.po

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,16 @@ msgid ""
88
msgstr ""
99
"Project-Id-Version: sphinx_rtd_theme 0.4.3.dev0\n"
1010
"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
11-
"POT-Creation-Date: 2021-08-17 10:02-0600\n"
11+
"POT-Creation-Date: 2023-02-06 15:36+0100\n"
1212
"PO-Revision-Date: 2019-07-16 15:43-0600\n"
1313
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
1414
"Language: en\n"
1515
"Language-Team: en <[email protected]>\n"
16-
"Plural-Forms: nplurals=2; plural=(n != 1)\n"
16+
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
1717
"MIME-Version: 1.0\n"
1818
"Content-Type: text/plain; charset=utf-8\n"
1919
"Content-Transfer-Encoding: 8bit\n"
20-
"Generated-By: Babel 2.8.0\n"
20+
"Generated-By: Babel 2.11.0\n"
2121

2222
#. This is an ARIA section label for page links, including previous/next page
2323
#. link and links to GitHub/GitLab/etc.
@@ -93,7 +93,7 @@ msgid "Built with %(sphinx_web)s using a"
9393
msgstr ""
9494

9595
#. "theme" refers to a theme for Sphinx, which alters the appearance of the
96-
#. generated documenation
96+
#. generated documentation
9797
#: sphinx_rtd_theme/footer.html:55
9898
msgid "theme"
9999
msgstr ""
@@ -126,18 +126,18 @@ msgstr ""
126126
msgid "Copyright"
127127
msgstr ""
128128

129-
#: sphinx_rtd_theme/layout.html:147 sphinx_rtd_theme/layout.html:149
129+
#: sphinx_rtd_theme/layout.html:143
130130
msgid "Logo"
131131
msgstr ""
132132

133133
#. This is an ARIA section label for the main navigation menu
134-
#: sphinx_rtd_theme/layout.html:173
134+
#: sphinx_rtd_theme/layout.html:166
135135
msgid "Navigation menu"
136136
msgstr ""
137137

138138
#. This is an ARIA section label for the navigation menu that is visible when
139139
#. viewing the page on mobile devices
140-
#: sphinx_rtd_theme/layout.html:195
140+
#: sphinx_rtd_theme/layout.html:188
141141
msgid "Mobile navigation menu"
142142
msgstr ""
143143

0 commit comments

Comments
 (0)