Skip to content

Add an explicit flyout placement option #9357

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 27, 2022
Merged

Add an explicit flyout placement option #9357

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
19072ce
Add an explicit flyout placement option
ericholscher Jun 20, 2022
30cef61
Address review feedback
ericholscher Jun 21, 2022
5d7c296
Rename placement to readthedocs-embed-flyout
ericholscher Jun 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/user/_static/images/flyout-closed.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/user/_static/images/flyout-open.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
121 changes: 121 additions & 0 deletions docs/user/flyout-menu.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
Flyout Menu
===========

When you are using a Read the Docs site,
you will likely notice that we embed a menu on all the documentation pages we serve.
This is a way to expose the functionality of Read the Docs on the page,
without having to have the documentation theme integrate it directly.

Functionality
-------------

The flyout menu provides access to the following bits of Read the Docs functionality:

* A :doc:`version switcher </versions>` that shows users all of the active, unhidden versions they have access to.
* :doc:`Downloadable formats </downloadable-documentation>` for the current version, including HTML & PDF downloads that are enabled by the project.
* Links to the Read the Docs dashboard for the project.
* Links to your :doc:`VCS provider </integrations>` that allow the user to quickly find the exact file that the documentation was rendered from.
* A search bar that gives users access to our :doc:`/server-side-search` of the current version.

Closed
~~~~~~

.. figure:: /_static/images/flyout-closed.png

The flyout when it's closed

Open
~~~~

.. figure:: /_static/images/flyout-open.png

The opened flyout

Information for theme authors
-----------------------------

People who are making custom documentation themes often want to specify where the flyout is injected,
and also what it looks like.
We support both of these use cases for themes.

Defining where the flyout menu is injected
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The flyout menu injection follows this logic:

* When a ``<div id="readthedocs-embed-placement">`` is defined, inject the flyout menu there.
* If a page is an old version of the Read the Docs Sphinx theme, update the place where the theme expected it to be injected.
* All other pages have the flyout appended to the ``<body>``

Styling the flyout
~~~~~~~~~~~~~~~~~~

HTML themes can style the flyout to make it match the overall style of the HTML.
By default the flyout has it's `own CSS file <https://github.com/readthedocs/sphinx_rtd_theme/blob/master/src/sass/_theme_badge.sass>`_,
which you can look at to see the basic CSS class names.
It also uses fontawesome to define some basic UI elements,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It also uses fontawesome to define some basic UI elements,
It also uses Font Awesome to define some basic UI elements,

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a PR opened to remove this and hardcode only the icons used. So, this may conflict with that. See #9297

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll go ahead and remove this mention for now, so we don't have to remember to remove it. That does seem like a better approach.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: Font Awesome isn't being removed, just the need for font files. It's still a Font Awesome licensed graphic.

which are exposed in the HTML with ``fa-`` classes.

The example HTML that the flyout uses is included here,
so that you can style it in your HTML theme:

.. code:: html

<div class="injected">
<div class="rst-versions rst-badge shift-up" data-toggle="rst-versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book">&nbsp;</span>
v: 2.1.x
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>Versions</dt>
<dd>
<a href="https://flask.palletsprojects.com/en/latest/">latest</a>
</dd>
<dd class="rtd-current-item">
<a href="https://flask.palletsprojects.com/en/2.1.x/">2.1.x</a>
</dd>
</dl>
<dl>
<!-- These are kept as relative links for internal installs that are http -->
<dt>On Read the Docs</dt>
<dd>
<a href="//readthedocs.org/projects/flask/">Project Home</a>
</dd>
<dd>
<a href="//readthedocs.org/projects/flask/builds/">Builds</a>
</dd>
<dd>
<a href="//readthedocs.org/projects/flask/downloads/">Downloads</a>
</dd>
</dl>
<dl>
<dt>On GitHub</dt>
<dd>
<a href="https://github.com/pallets/flask/blob/2.1.x/docs/index.rst">View</a>
</dd>
<dd>
<a href="https://github.com/pallets/flask/edit/2.1.x/docs/index.rst">Edit</a>
</dd>
</dl>
<dl>
<dt>Search</dt>
<dd>
<div style="padding: 6px;">
<form id="flyout-search-form" class="wy-form" target="_blank" action="//readthedocs.org/projects/flask/search/" method="get">
<input type="text" name="q" aria-label="Search docs" placeholder="Search docs">
</form>
</div>
</dd>
</dl>
<hr>
<small>
<span>Hosted by <a href="https://readthedocs.org">Read the Docs</a></span>
<span> · </span>
<a href="https://docs.readthedocs.io/page/privacy-policy.html">Privacy Policy</a>
</small>
</div>
</div>
</div>
4 changes: 2 additions & 2 deletions docs/user/glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Glossary
and import a new project.

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

pre-defined build jobs
Commands executed by Read the Docs when performing the build process.
Expand Down
2 changes: 2 additions & 0 deletions docs/user/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,7 @@ out of your documentation and Read the Docs.
* **Advanced project configuration**:
:doc:`subprojects` |
:doc:`Single version docs <single_version>` |
:doc:`flyout-menu` |
:doc:`feature-flags`

* **Multi-language documentation**:
Expand All @@ -202,6 +203,7 @@ out of your documentation and Read the Docs.

subprojects
single_version
flyout-menu
feature-flags

localization
Expand Down
6 changes: 3 additions & 3 deletions docs/user/versions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,12 +71,12 @@ Hidden

- **Not hidden and Active**

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

- **Hidden and Active**

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

Expand Down Expand Up @@ -118,7 +118,7 @@ Logging out
'''''''''''

When you log in to a documentation site, you will be logged in until close your browser.
To log out, click on the :guilabel:`Log out` link in your documentation's flyout menu.
To log out, click on the :guilabel:`Log out` link in your documentation's :term:`flyout menu`.
This is usually located in the bottom right or bottom left, depending on the theme design.
This will log you out from the current domain,
but not end any other session that you have active.
Expand Down
17 changes: 12 additions & 5 deletions readthedocs/core/static-src/core/js/doc-embed/footer.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
var rtddata = require('./rtd-data');
var versionCompare = require('./version-compare');

var EXPLICIT_FLYOUT_PLACEMENT_SELECTOR = '#readthedocs-embed-placement';


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

// If the theme looks like ours, update the existing badge
// otherwise throw a a full one into the page.
// Do not inject for mkdocs even for the RTD theme
if (config.is_sphinx_builder() && config.is_rtd_like_theme()) {
var config = rtddata.get();
if ($(EXPLICIT_FLYOUT_PLACEMENT_SELECTOR).length > 0) {
$(EXPLICIT_FLYOUT_PLACEMENT_SELECTOR).html(data['html']);
}
else if (config.is_sphinx_builder() && config.is_rtd_like_theme()) {
$("div.rst-other-versions").html(data['html']);
} else {
$("body").append(data['html']);
Expand Down