Skip to content

Commit b4cc7c9

Browse files
ericholscherericholscher
authored
Add an explicit flyout placement option (#9357)
This PR does a few things: * Lets themes define a `#readthedocs-embed-placement` element, where we will inject the footer * Documents the flyout menu under Advanced Features Refs pydata/pydata-sphinx-theme#705 * Address review feedback * Rename placement to readthedocs-embed-flyout
1 parent 3adf24e commit b4cc7c9

File tree

7 files changed

+139
-10
lines changed

7 files changed

+139
-10
lines changed

‎docs/user/_static/images/flyout-closed.png

5.98 KB
Loading

‎docs/user/_static/images/flyout-open.png

32.8 KB
Loading

‎docs/user/flyout-menu.rst

+119
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
Flyout Menu
2+
===========
3+
4+
When you are using a Read the Docs site,
5+
you will likely notice that we embed a menu on all the documentation pages we serve.
6+
This is a way to expose the functionality of Read the Docs on the page,
7+
without having to have the documentation theme integrate it directly.
8+
9+
Functionality
10+
-------------
11+
12+
The flyout menu provides access to the following bits of Read the Docs functionality:
13+
14+
* A :doc:`version switcher </versions>` that shows users all of the active, unhidden versions they have access to.
15+
* :doc:`Downloadable formats </downloadable-documentation>` for the current version, including HTML & PDF downloads that are enabled by the project.
16+
* Links to the Read the Docs dashboard for the project.
17+
* Links to your :doc:`VCS provider </integrations>` that allow the user to quickly find the exact file that the documentation was rendered from.
18+
* A search bar that gives users access to our :doc:`/server-side-search` of the current version.
19+
20+
Closed
21+
~~~~~~
22+
23+
.. figure:: /_static/images/flyout-closed.png
24+
25+
The flyout when it's closed
26+
27+
Open
28+
~~~~
29+
30+
.. figure:: /_static/images/flyout-open.png
31+
32+
The opened flyout
33+
34+
Information for theme authors
35+
-----------------------------
36+
37+
People who are making custom documentation themes often want to specify where the flyout is injected,
38+
and also what it looks like.
39+
We support both of these use cases for themes.
40+
41+
Defining where the flyout menu is injected
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
The flyout menu injection looks for a specific selector (``#readthedocs-embed-flyout``),
45+
in order to inject the flyout.
46+
You can add ``<div id="readthedocs-embed-flyout">`` in your theme,
47+
and our JavaScript code will inject the flyout there.
48+
All other themes except for the ``sphinx_rtd_theme`` have the flyout appended to the ``<body>``.
49+
50+
Styling the flyout
51+
~~~~~~~~~~~~~~~~~~
52+
53+
HTML themes can style the flyout to make it match the overall style of the HTML.
54+
By default the flyout has it's `own CSS file <https://github.com/readthedocs/sphinx_rtd_theme/blob/master/src/sass/_theme_badge.sass>`_,
55+
which you can look at to see the basic CSS class names.
56+
57+
The example HTML that the flyout uses is included here,
58+
so that you can style it in your HTML theme:
59+
60+
.. code:: html
61+
62+
<div class="injected">
63+
<div class="rst-versions rst-badge shift-up" data-toggle="rst-versions">
64+
<span class="rst-current-version" data-toggle="rst-current-version">
65+
<span class="fa fa-book">&nbsp;</span>
66+
v: 2.1.x
67+
<span class="fa fa-caret-down"></span>
68+
</span>
69+
<div class="rst-other-versions">
70+
<dl>
71+
<dt>Versions</dt>
72+
<dd>
73+
<a href="https://flask.palletsprojects.com/en/latest/">latest</a>
74+
</dd>
75+
<dd class="rtd-current-item">
76+
<a href="https://flask.palletsprojects.com/en/2.1.x/">2.1.x</a>
77+
</dd>
78+
</dl>
79+
<dl>
80+
<!-- These are kept as relative links for internal installs that are http -->
81+
<dt>On Read the Docs</dt>
82+
<dd>
83+
<a href="//readthedocs.org/projects/flask/">Project Home</a>
84+
</dd>
85+
<dd>
86+
<a href="//readthedocs.org/projects/flask/builds/">Builds</a>
87+
</dd>
88+
<dd>
89+
<a href="//readthedocs.org/projects/flask/downloads/">Downloads</a>
90+
</dd>
91+
</dl>
92+
<dl>
93+
<dt>On GitHub</dt>
94+
<dd>
95+
<a href="https://github.com/pallets/flask/blob/2.1.x/docs/index.rst">View</a>
96+
</dd>
97+
<dd>
98+
<a href="https://github.com/pallets/flask/edit/2.1.x/docs/index.rst">Edit</a>
99+
</dd>
100+
</dl>
101+
<dl>
102+
<dt>Search</dt>
103+
<dd>
104+
<div style="padding: 6px;">
105+
<form id="flyout-search-form" class="wy-form" target="_blank" action="//readthedocs.org/projects/flask/search/" method="get">
106+
<input type="text" name="q" aria-label="Search docs" placeholder="Search docs">
107+
</form>
108+
</div>
109+
</dd>
110+
</dl>
111+
<hr>
112+
<small>
113+
<span>Hosted by <a href="https://readthedocs.org">Read the Docs</a></span>
114+
<span> · </span>
115+
<a href="https://docs.readthedocs.io/page/privacy-policy.html">Privacy Policy</a>
116+
</small>
117+
</div>
118+
</div>
119+
</div>

‎docs/user/glossary.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ Glossary
88
and import a new project.
99

1010
flyout menu
11-
Menu displayed on the documentation, readily accessible for readers, containing the list active versions,
12-
links to the static downloads, and other useful information.
11+
Menu displayed on the documentation, readily accessible for readers, containing the list active versions, links to static downloads, and other useful links.
12+
Read more in our :doc:`/flyout-menu` page.
1313

1414
pre-defined build jobs
1515
Commands executed by Read the Docs when performing the build process.

‎docs/user/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,7 @@ out of your documentation and Read the Docs.
176176
* **Advanced project configuration**:
177177
:doc:`subprojects` |
178178
:doc:`Single version docs <single_version>` |
179+
:doc:`flyout-menu` |
179180
:doc:`feature-flags`
180181

181182
* **Multi-language documentation**:
@@ -201,6 +202,7 @@ out of your documentation and Read the Docs.
201202

202203
subprojects
203204
single_version
205+
flyout-menu
204206
feature-flags
205207

206208
localization

‎docs/user/versions.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -71,12 +71,12 @@ Hidden
7171

7272
- **Not hidden and Active**
7373

74-
- This version is listed on the version (flyout) menu on the docs site
74+
- This version is listed on the :term:`flyout menu` on the docs site
7575
- This version is shown in search results on the docs site
7676

7777
- **Hidden and Active**
7878

79-
- This version isn't listed on the version (flyout) menu on the docs site
79+
- This version isn't listed on the :term:`flyout menu` on the docs site
8080
- This version isn't shown in search results from another version on the docs site
8181
(like on search results from a superproject)
8282

@@ -118,7 +118,7 @@ Logging out
118118
'''''''''''
119119

120120
When you log in to a documentation site, you will be logged in until close your browser.
121-
To log out, click on the :guilabel:`Log out` link in your documentation's flyout menu.
121+
To log out, click on the :guilabel:`Log out` link in your documentation's :term:`flyout menu`.
122122
This is usually located in the bottom right or bottom left, depending on the theme design.
123123
This will log you out from the current domain,
124124
but not end any other session that you have active.

‎readthedocs/core/static-src/core/js/doc-embed/footer.js

+13-5
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,22 @@
11
var rtddata = require('./rtd-data');
22
var versionCompare = require('./version-compare');
33

4+
var EXPLICIT_FLYOUT_PLACEMENT_SELECTOR = '#readthedocs-embed-flyout';
5+
46

57
function injectFooter(data) {
6-
var config = rtddata.get();
8+
// Injects the footer into the page
9+
// There are 3 main cases:
10+
// * EXPLICIT_FLYOUT_PLACEMENT_SELECTOR is defined, inject it there
11+
// * The page looks like our Sphinx theme, updated the existing div
12+
// * All other pages just get it appended to the <body>
713

8-
// If the theme looks like ours, update the existing badge
9-
// otherwise throw a a full one into the page.
10-
// Do not inject for mkdocs even for the RTD theme
11-
if (config.is_sphinx_builder() && config.is_rtd_like_theme()) {
14+
var config = rtddata.get();
15+
var placement = $(EXPLICIT_FLYOUT_PLACEMENT_SELECTOR);
16+
if (placement.length > 0) {
17+
placement.html(data['html']);
18+
}
19+
else if (config.is_sphinx_builder() && config.is_rtd_like_theme()) {
1220
$("div.rst-other-versions").html(data['html']);
1321
} else {
1422
$("body").append(data['html']);

0 commit comments

Comments
 (0)