Clean up Addons & Flyout menu docs (#11706)

* Clean up Addons & Flyout menu docs This cleans up the copy here, adds the DocDiff page, and clarifies as bit more the Custom event language. * Update docs/user/flyout-menu.rst Co-authored-by: Manuel Kaufmann <[email protected]> --------- Co-authored-by: Manuel Kaufmann <[email protected]>
readthedocs · Oct 28, 2024 · 727da6e · 727da6e
1 parent ad74e78
commit 727da6e
Show file tree

Hide file tree

Showing 8 changed files with 103 additions and 54 deletions.
diff --git a/docs/user/_static/images/flyout-open.png b/docs/user/_static/images/flyout-open.png
diff --git a/docs/user/addons.rst b/docs/user/addons.rst
@@ -1,44 +1,36 @@
 Read the Docs Addons
 ====================
 
-**Read the Docs Addons** is a group of features for documentation readers and maintainers that you can add to any documentation set hosted on Read the Docs:
+**Read the Docs Addons** is a group of features for documentation readers and maintainers that you can add to any documentation set hosted on Read the Docs.
+They are used in the rendered documentation,
+and can be accessed via hotkeys or on screen UI elements.
 
 :doc:`DocDiff </pull-requests>`
-    highlight changed output from pull requests
+    Highlight changed output from pull requests
 
 :doc:`Pull request notification </pull-requests>`
-    notify readers that they are reading docs from a pull request
+    Notify readers that they are reading docs from a pull request
 
 :doc:`Flyout </flyout-menu>`
-    easily switch between versions and translations
+    Easily switch between versions and translations
 
 :doc:`Non-stable notification </versions>`
-    notify readers that they are reading docs from a non stable release
+    Notify readers that they are reading docs from a non stable release
 
 :doc:`Latest version notification </versions>`
-    notify readers that they are reading docs from a development version
+    Notify readers that they are reading docs from a development version
 
 :doc:`Search as you type </server-side-search/index>`
-    get search results faster
+    Get search results faster
 
-Enabling Read the Docs Addons
------------------------------
-
-All projects using ``mkdocs`` :ref:`mkdocs <config-file/v2:mkdocs>` or the ``build.command`` :ref:`build command <config-file/v2:build.commands>` are already using the Addons, other projects can enable them by following these steps:
-
-#. Go to the new dashboard:
-
-    * `Community <https://app.readthedocs.org>`_
-    * `Business <https://app.readthedocs.com>`_
-
-#. Click on a project name.
-#. Go to :guilabel:`Settings`, then in the left bar, go to :guilabel:`Addons`.
-#. Check :guilabel:`Enable Addons`, and then configure each Addon individually.
+:doc:`DocDiff </pull-requests>`
+    Highlight changed output from pull requests
 
-.. note::
+:doc:`Traffic analytics </traffic-analytics>`
+    See what pages your users are reading
 
-    Read the Docs Addons will be enabled by default for all Read the Docs projects on October 7th.
-    Read the full announcement in our `blog post <https://about.readthedocs.com/blog/2024/07/addons-by-default/>`_.
+:doc:`Search analytics </search-analytics>`
+    Understand what your users are searching for
 
 Configuring Read the Docs Addons
 --------------------------------
@@ -51,5 +43,19 @@ Individual configuration options for each addon are available in :guilabel:`Sett
     * `Business <https://app.readthedocs.com>`_
 
 #. Click on a project name.
-#. Go to :guilabel:`Settings`, then in the left bar, go to :guilabel:`Addons`.
+#. Go to :guilabel:`Settings`
+#. In the left bar, go to :guilabel:`Addons`.
 #. Configure each Addon individually.
+
+Addons data and customization
+-----------------------------
+
+If you'd like to do a custom integration with the data used to render Addons,
+you can learn more about this in our :ref:`flyout-menu:custom event integration` docs.
+
+Diving deeper
+-------------
+
+You can read more about all of the Addons functionality by diving into each Addon above.
+If you are a developer and would like to integrate with our Addons or use our existing data,
+you can :doc:`reach out </support>` to us and we would love to work with you.
diff --git a/docs/user/doc-diff.rst b/docs/user/doc-diff.rst
@@ -0,0 +1,29 @@
+DocDiff
+=======
+
+DocDiff allows you to see a visual :term:`diff` on a documentation page,
+showing what has changed between the ``latest`` version and the active :doc:`pull request </pull-requests>`.
+
+DocDiff allows you to quickly review changes visually,
+and focus your review on what has changed in the current page.
+
+.. figure:: /img/addons-docdiff.gif
+   :width: 80%
+
+   Example of DocDiff
+
+Enabling DocDiff
+----------------
+
+DocDiff is only enabled on pull request builds,
+and can be toggled on and off with the ``d`` hotkey.
+
+Troubleshooting DocDiff
+-----------------------
+
+DocDiff only works if there are changes on the page,
+so ensure you are on a page that has changed in the current pull request.
+
+There are also some known issues that currently don't display properly:
+
+* **Tables** are shown to have changes when they may not have changed. This is due to do subtly in how HTML tables are rendered, and will be fixed in a future version.
diff --git a/docs/user/flyout-menu.rst b/docs/user/flyout-menu.rst
@@ -3,21 +3,27 @@
 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,
+When you use a Read the Docs site,
+there is a flyout menu embedded on all the documentation pages.
+The flyout menu is a way to expose the functionality of Read the Docs on the page,
 without having to have the documentation theme integrate it directly.
 
-There are two versions of the flyout menu:
-
-- :ref:`flyout-menu:Addons flyout menu`
-- :ref:`flyout-menu:Original flyout menu`
+.. tip::
+   The flyout menu is a default implementation that works for every site.
+   You can access the full data used to construct the flyout,
+   and use that to integrate the data directly into your documentation theme for a nicer user experience.
+   See the :ref:`Custom event integration` for more information.
 
 Addons flyout menu
 ------------------
 
-The updated :doc:`addons` flyout menu lists available documentation versions and translations, as well as useful links,
-offline formats, and a search bar.
+The :doc:`addons` flyout provides a place for a number of Read the Docs features:
+
+* A :doc:`version switcher </versions>` that shows users all of the active versions they have access to.
+* A :doc:`translation switcher </internationalization>` that shows all the documentation languages provided.
+* A list of :doc:`offline formats </downloadable-documentation>` for the current version, including HTML & PDF downloads.
+* Links to the Read the Docs dashboard for the project.
+* A search bar that gives users access to the :doc:`/server-side-search/index` of the current version.
 
 .. figure:: /_static/images/flyout-addons.png
    :align: center
@@ -27,31 +33,34 @@ offline formats, and a search bar.
 Customizing the flyout menu
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In your dashboard, you can configure flyout menu options in :guilabel:`Settings`, under :guilabel:`Addons`.
+In your dashboard, you can configure flyout menu options in :guilabel:`Settings > Addons > Flyout Menu`.
 
-Sort your versions :guilabel:`Alphabetically`, by :guilabel:`SemVer`, by :guilabel:`Python Packaging`,
-by :guilabel:`CalVer`, or define your own pattern.
+Version sorting
+^^^^^^^^^^^^^^^
 
-Choose whether to list stable versions first or not.
+The primary customization currently is the ability to sort versions.
+You can sort by:
 
-Customizing the look of the addons flyout menu
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. TODO: Define how these work better..
 
-The addons flyout exposes all the required data to build the flyout menu via a JavaScript ``CustomEvent``.
-Take a look at an example of this approach at https://github.com/readthedocs/sphinx_rtd_theme/pull/1526.
+* :guilabel:`SemVer (Read the Docs)` - **Default**. Read the Docs custom implementation of semver.org.
+* :guilabel:`Python Packaging` - Sort by Python packaging sorting.
+* :guilabel:`CalVer` - Sort by calendar date.
+* :guilabel:`Alphabetically` - Only useful if you aren't using numeric versions.
+* Or you can define a custom pattern
 
-Original flyout menu
---------------------
+You can also choose whether ``latest`` and ``stable`` should be sorted first,
+as those are special versions that Read the Docs uses.
 
-The flyout menu provides access to the following bits of Read the Docs functionality:
+Custom event integration
+------------------------
 
-* A :doc:`version switcher </versions>` that shows users all of the active, unhidden versions they have access to.
-* :doc:`Offline 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:`Git provider </reference/git-integration>` 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/index` of the current version.
-
-.. figure:: /_static/images/flyout-open.png
-   :align: center
+Read the Docs Addons exposes all the data used to construct the flyout menu via a JavaScript ``CustomEvent``.
+If you'd like to integrate the data,
+you can use the :ref:`mkdocs:Integrate the Read the Docs version menu into your site navigation` example as a starting point.
 
-   The opened flyout
+.. warning::
+   We have not formally documented the API response returned from the Addons API,
+   but you can view the JSON data returned there as a starting point.
+   Once we document it,
+   we will commit to supporting that version of the API response going forward.
diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst
@@ -31,6 +31,10 @@ so that you have a reference for how we're using them.
       Projects have a *default version*, usually the latest stable version of a project.
       The *default version* is the URL that is redirected to when a users loads the `/` URL for your project.
 
+   diff
+      A way to see the changes between two pieces of text,
+      which shows the added and removed content with a green and red color respectively.
+
    discoverability
       A documentation page is said to be *discoverable* when a user that needs it can find it through various methods:
       Navigation, search, and links from other pages are the most typical ways of making content *discoverable*.

diff --git a/docs/user/img/addons-docdiff.gif b/docs/user/img/addons-docdiff.gif
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -59,6 +59,7 @@ Read the Docs: documentation simplified
    :caption: Reading documentation
 
    /downloadable-documentation
+   /doc-diff
    /guides/embedding-content
    /server-side-search/index
    /server-side-search/syntax

diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst
@@ -28,7 +28,7 @@ Pull request notifications
     A pull request notifications is shown at the top of preview pages,
     which let readers know they aren't viewing an active version of the project.
 
-DocDiff
+:doc:`DocDiff </doc-diff>``
     DocDiff shows proposed changes by visually highlighting the differences between the current pull request and the latest version of the project's documentation.
 
     Press ``d`` to toggle between DocDiff and normal pull request preview.