diff --git a/docs/user/_static/images/flyout-closed.png b/docs/user/_static/images/flyout-closed.png new file mode 100644 index 00000000000..d5bf7b5e5ba Binary files /dev/null and b/docs/user/_static/images/flyout-closed.png differ diff --git a/docs/user/_static/images/flyout-open.png b/docs/user/_static/images/flyout-open.png new file mode 100644 index 00000000000..5de4c63bf76 Binary files /dev/null and b/docs/user/_static/images/flyout-open.png differ diff --git a/docs/user/flyout-menu.rst b/docs/user/flyout-menu.rst new file mode 100644 index 00000000000..0a62ed76f1a --- /dev/null +++ b/docs/user/flyout-menu.rst @@ -0,0 +1,119 @@ +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 ` that shows users all of the active, unhidden versions they have access to. +* :doc:`Downloadable formats ` 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 ` 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 looks for a specific selector (``#readthedocs-embed-flyout``), +in order to inject the flyout. +You can add ``
`` in your theme, +and our JavaScript code will inject the flyout there. +All other themes except for the ``sphinx_rtd_theme`` have the flyout appended to the ````. + +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 `_, +which you can look at to see the basic CSS class names. + +The example HTML that the flyout uses is included here, +so that you can style it in your HTML theme: + +.. code:: html + +
+
+ +   + v: 2.1.x + + +
+
+
Versions
+
+ latest +
+
+ 2.1.x +
+
+
+ +
On Read the Docs
+
+ Project Home +
+
+ Builds +
+
+ Downloads +
+
+
+
On GitHub
+
+ View +
+
+ Edit +
+
+
+
Search
+
+
+
+ +
+
+
+
+
+ + Hosted by Read the Docs + ยท + Privacy Policy + +
+
+
diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index fe071bd2c1b..53c5b8610f5 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -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. diff --git a/docs/user/index.rst b/docs/user/index.rst index 6fc4eb23d64..3000d525fce 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -176,6 +176,7 @@ out of your documentation and Read the Docs. * **Advanced project configuration**: :doc:`subprojects` | :doc:`Single version docs ` | + :doc:`flyout-menu` | :doc:`feature-flags` * **Multi-language documentation**: @@ -201,6 +202,7 @@ out of your documentation and Read the Docs. subprojects single_version + flyout-menu feature-flags localization diff --git a/docs/user/versions.rst b/docs/user/versions.rst index 46f529451dc..30d4a242023 100644 --- a/docs/user/versions.rst +++ b/docs/user/versions.rst @@ -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) @@ -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. diff --git a/readthedocs/core/static-src/core/js/doc-embed/footer.js b/readthedocs/core/static-src/core/js/doc-embed/footer.js index 8d14becbe21..a6f6d9b76ce 100644 --- a/readthedocs/core/static-src/core/js/doc-embed/footer.js +++ b/readthedocs/core/static-src/core/js/doc-embed/footer.js @@ -1,14 +1,22 @@ var rtddata = require('./rtd-data'); var versionCompare = require('./version-compare'); +var EXPLICIT_FLYOUT_PLACEMENT_SELECTOR = '#readthedocs-embed-flyout'; + 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 - // 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(); + var placement = $(EXPLICIT_FLYOUT_PLACEMENT_SELECTOR); + if (placement.length > 0) { + placement.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']);