From 9539ae9263026949a2cd4943854187dfefe883a4 Mon Sep 17 00:00:00 2001
From: Sam <samuel@plaindocs.com>
Date: Mon, 11 Nov 2024 13:51:57 +0100
Subject: [PATCH] Clarify flyout options (#11750)

Fix up for the new options on this old PR.

<!-- readthedocs-preview docs start -->
---
:books: Documentation previews :books:

- User's documentation (`docs`):
https://docs--11750.org.readthedocs.build/en/11750/

<!-- readthedocs-preview docs end -->

<!-- readthedocs-preview dev start -->
- Developer's documentation (`dev`):
https://dev--11750.org.readthedocs.build/en/11750/

<!-- readthedocs-preview dev end -->

Co-authored-by: Manuel Kaufmann <humitos@gmail.com>
---
 docs/user/intro/sphinx.rst | 24 ++++++------------------
 1 file changed, 6 insertions(+), 18 deletions(-)

diff --git a/docs/user/intro/sphinx.rst b/docs/user/intro/sphinx.rst
index 4767770bfae..7cbf34a3ab8 100644
--- a/docs/user/intro/sphinx.rst
+++ b/docs/user/intro/sphinx.rst
@@ -101,28 +101,16 @@ If you're using a different theme, enable :doc:`Server side search </server-side
              ("readthedocs.js", {"defer": "defer"}),
          ]
 
+Integrate the Read the Docs version menu into your site navigation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. TODO: adapt and uncomment this section.
-   We've changed `flyout_display` to be `hidden` by default;
-   If people want to use the integrated version of it, they should declare it as `attached`.
-   However, as we have the version/language selectors now,
-   we want to promote that more and keep the Addons flyout enabled by default.
+The :ref:`flyout-menu:Addons flyout menu` displays differently depending to which Sphinx theme your documentation uses.
 
-   Integrate the Read the Docs version menu into your site navigation
-   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- If you're using the `Read the Docs Sphinx Theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__, the :ref:`flyout-menu:Addons flyout menu` is already fully integrated into the theme. Use the theme options `flyout_display <https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-flyout_display>`__, `version_selector <https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-version_selector>`__, `language_selector <https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-language_selector>`__ to configure it.
 
-   If you're using the `Read the Docs Sphinx Theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__, the :ref:`flyout-menu:Addons flyout menu` is already fully integrated.
+- If you're using another theme, the flyout menu displays in the bottom right of the docs.
 
-   You *may* need to set `flyout_display` to `hidden <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html#confval-flyout_display>`_ in your ``conf.py`` so as not to display two identical menus:
-
-   .. code-block:: py
-      :caption: conf.py
-
-       html_theme_options = {
-           "flyout_display": "hidden",
-       }
-
-   If you're using a different theme, the flyout menu will display in the default bottom right side of your docs.
+In either case, you can configure the flyout menu sorting and display options in :guilabel:`Settings`, under :guilabel:`Addons`.
 
 Using Markdown with Sphinx
 --------------------------