Skip to content

Commit 357e76d

Browse files
humitosagjohnson
humitos
and
agjohnson
authored
Addons: integrate with new beta addons flyout (#1526)
* Addons: integrate with new beta addons flyout Initial experimentation to use the `CustomEvent` triggered by the addons called `readthedocsdataready` event (from readthedocs/addons#64) to build the Read the Docs flyout being integrated into the theme keeping the original look & feel. * Related: readthedocs/addons#64 * Closes #1523 * `READTHEDOCS` variable has to be passed to the `html_context` This is because we are not executing the Read the Docs magic that modifies the `conf.py` file on the fly :/ * Update code to match the latest changes * Use `.join` to avoid rendering the Array with `,` * Update code to use the v1 API structure response * Don't auto-remove the original flyout This can be disabled per-project by using the settings UI from the dashboard. * Join the values to avoid strange `,`s * Support translations Use the current pattern to translate string generated for the flyout. * Remove HTML tags for testing * Show "Search" section on flyout * Render footer * Add some styling * TODO comments to work on * add `div.injected` * Apply suggestions from code review Co-authored-by: Anthony <[email protected]> * Translate privacy policy * Add `.rtd-current-item` class to selected version/language * Refactor code to show sections only if there is content * Epub instead of EPUB for backward compatibility * Show the modal when clicking on the "Search docs" from navbar * Remove privacy policy link from flyout * Add UTM analytics * Move CSS style into SASS file * Move the `script` tag into its own file * Rename JS file to mark it as a Sphinx template * Build css/js files Run `npm ci` and `npm run build` using NodeJS 14.20.1. * Add the JS template in the package --------- Co-authored-by: Anthony <[email protected]>
1 parent 28c377f commit 357e76d

File tree

8 files changed

+144
-36
lines changed

8 files changed

+144
-36
lines changed

‎MANIFEST.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ recursive-include sphinx_rtd_theme *.css
77
recursive-include sphinx_rtd_theme *.eot
88
recursive-include sphinx_rtd_theme *.html
99
recursive-include sphinx_rtd_theme *.js
10+
recursive-include sphinx_rtd_theme *.js_t
1011
recursive-include sphinx_rtd_theme *.svg
1112
recursive-include sphinx_rtd_theme *.ttf
1213
recursive-include sphinx_rtd_theme *.woff

‎docs/conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@
6868
range(1, 100)
6969
))
7070

71+
if 'READTHEDOCS' in os.environ:
72+
html_context['READTHEDOCS'] = True
73+
html_context['READTHEDOCS_PROJECT'] = os.environ.get("READTHEDOCS_PROJECT")
74+
7175
html_logo = "demo/static/logo-wordmark-light.svg"
7276
html_show_sourcelink = True
7377
html_favicon = "demo/static/favicon.ico"

‎sphinx_rtd_theme/layout.html‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@
1616
<html class="writer-html5" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
1717
<head>
1818
<meta charset="utf-8" />
19+
{%- if READTHEDOCS and not embedded %}
20+
<meta name="readthedocs-addons-api-version" content="1">
21+
{%- endif %}
1922
{{- metatags }}
2023
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
2124
{%- block htmltitle %}
@@ -64,6 +67,10 @@
6467
{%- endfor %}
6568
<script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
6669

70+
{%- if READTHEDOCS %}
71+
<script src="{{ pathto('_static/js/versions.js', 1) }}"></script>
72+
{%- endif %}
73+
6774
{#- OPENSEARCH #}
6875
{%- if use_opensearch %}
6976
<link rel="search" type="application/opensearchdescription+xml"

‎sphinx_rtd_theme/static/css/badge_only.css‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎sphinx_rtd_theme/static/css/theme.css‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎sphinx_rtd_theme/static/js/versions.js_t‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
function renderLanguages(config) {
2+
if (!config.projects.translations.length) {
3+
return "";
4+
}
5+
6+
const languagesHTML = `
7+
<dl>
8+
<dt>{{ _('Languages') }}</dt>
9+
${ config.projects.translations.map(
10+
(translation) => `
11+
<dd ${ translation.slug == config.projects.current.slug ? 'class="rtd-current-item"' : '' }>
12+
<a href="${ translation.urls.documentation }">${ translation.language.code }</a>
13+
</dd>
14+
`).join("\n")}
15+
</dl>
16+
`;
17+
return languagesHTML;
18+
}
19+
20+
function renderVersions(config) {
21+
if (!config.versions.active.length) {
22+
return "";
23+
}
24+
const versionsHTML = `
25+
<dl>
26+
<dt>{{ _('Versions') }}</dt>
27+
${ config.versions.active.map(
28+
(version) => `
29+
<dd ${ version.slug === config.versions.current.slug ? 'class="rtd-current-item"' : '' }>
30+
<a href="${ version.urls.documentation }">${ version.slug }</a>
31+
</dd>
32+
`).join("\n")}
33+
</dl>
34+
`;
35+
return versionsHTML;
36+
}
37+
38+
function renderDownloads(config) {
39+
if (!Object.keys(config.versions.current.downloads).length) {
40+
return "";
41+
}
42+
const downloadsNameDisplay = {
43+
pdf: "PDF",
44+
epub: "Epub",
45+
htmlzip: "HTML",
46+
};
47+
48+
const downloadsHTML = `
49+
<dl>
50+
<dt>{{ _('Downloads') }}</dt>
51+
${ Object.entries(config.versions.current.downloads).map(
52+
([name, url]) => `
53+
<dd>
54+
<a href="${ url }">${ downloadsNameDisplay[name] }</a>
55+
</dd>
56+
`).join("\n")}
57+
</dl>
58+
`;
59+
return downloadsHTML;
60+
}
61+
62+
document.addEventListener("readthedocs-addons-data-ready", function(event) {
63+
const config = event.detail.data();
64+
65+
const flyout = `
66+
<div class="rst-versions" data-toggle="rst-versions" role="note">
67+
<span class="rst-current-version" data-toggle="rst-current-version">
68+
<span class="fa fa-book"> Read the Docs</span>
69+
v: ${ config.versions.current.slug }
70+
<span class="fa fa-caret-down"></span>
71+
</span>
72+
<div class="rst-other-versions">
73+
<div class="injected">
74+
${ renderLanguages(config) }
75+
${ renderVersions(config) }
76+
${ renderDownloads(config) }
77+
<dl>
78+
<dt>{{ _('On Read the Docs') }}</dt>
79+
<dd>
80+
<a href="${ config.projects.current.urls.home }">{{ _('Project Home') }}</a>
81+
</dd>
82+
<dd>
83+
<a href="${ config.projects.current.urls.builds }">{{ _('Builds') }}</a>
84+
</dd>
85+
<dd>
86+
<a href="${ config.projects.current.urls.downloads }">{{ _('Downloads') }}</a>
87+
</dd>
88+
</dl>
89+
<dl>
90+
<dt>{{ _('Search') }}</dt>
91+
<dd>
92+
<form id="flyout-search-form">
93+
<input
94+
class="wy-form"
95+
type="text"
96+
name="q"
97+
aria-label="{{ _('Search docs') }}"
98+
placeholder="{{ _('Search docs') }}"
99+
/>
100+
</form>
101+
</dd>
102+
</dl>
103+
<hr />
104+
<small>
105+
<span>Hosted by <a href="https://about.readthedocs.org/?utm_source={{ READTHEDOCS_PROJECT }}&utm_content=flyout">Read the Docs</a></span>
106+
</small>
107+
</div>
108+
</div>
109+
`;
110+
111+
// Inject the generated flyout into the body HTML element.
112+
document.body.insertAdjacentHTML("beforeend", flyout);
113+
114+
// Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout.
115+
document.querySelector("#flyout-search-form").addEventListener("focusin", () => {
116+
const event = new CustomEvent("readthedocs-search-show");
117+
document.dispatchEvent(event);
118+
});
119+
120+
// Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
121+
document.querySelector("[role='search'] input").addEventListener("focusin", () => {
122+
const event = new CustomEvent("readthedocs-search-show");
123+
document.dispatchEvent(event);
124+
});
125+
});

‎sphinx_rtd_theme/versions.html‎

Lines changed: 0 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +0,0 @@
1-
{% if READTHEDOCS %}
2-
{# Add rst-badge after rst-versions for small badge style. #}
3-
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Versions') }}">
4-
<span class="rst-current-version" data-toggle="rst-current-version">
5-
<span class="fa fa-book"> Read the Docs</span>
6-
v: {{ current_version }}
7-
<span class="fa fa-caret-down"></span>
8-
</span>
9-
<div class="rst-other-versions">
10-
<dl>
11-
<dt>{{ _('Versions') }}</dt>
12-
{% for slug, url in versions %}
13-
<dd><a href="{{ url }}">{{ slug }}</a></dd>
14-
{% endfor %}
15-
</dl>
16-
<dl>
17-
<dt>{{ _('Downloads') }}</dt>
18-
{% for type, url in downloads %}
19-
<dd><a href="{{ url }}">{{ type }}</a></dd>
20-
{% endfor %}
21-
</dl>
22-
<dl>
23-
{# Translators: The phrase "Read the Docs" is not translated #}
24-
<dt>{{ _('On Read the Docs') }}</dt>
25-
<dd>
26-
<a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _('Project Home') }}</a>
27-
</dd>
28-
<dd>
29-
<a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _('Builds') }}</a>
30-
</dd>
31-
</dl>
32-
</div>
33-
</div>
34-
{% endif %}

‎src/sass/_theme_badge.sass‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@
5858
display: inline-block
5959
padding: $base-line-height / 4
6060
color: $section-background-color
61+
.rtd-current-item
62+
font-weight: bold
6163
&.rst-badge
6264
width: auto
6365
bottom: 20px
@@ -92,3 +94,6 @@
9294
display: none
9395
&.shift
9496
display: block
97+
98+
#flyout-search-form
99+
padding: 6px

0 commit comments

Comments
 (0)