Add minimal viable docs for addons

docs/user/addons.rst

@@ -0,0 +1,27 @@
+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:
+
+- :doc:`Traffic analytics </analytics>`
+- :doc:`DocDiff </pull-requests>`
+- :doc:`Pull request notification </pull-requests>`
+- :doc:`Flyout </flyout-menu>`
+- :doc:`Non-stable notification </notifications>`
+- :doc:`Latest version notification </notifications>`
+- :doc:`Search as you type </server-side-search/index>`
+- :ref:`Sponsorship <sponsors:sponsorship information>`
+
+Enabling Read the Docs Addons
+-----------------------------
+
+All projects using 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 beta dashboard:
+
+    * `Community <https://beta.readthedocs.org>`_
+    * `Business <https://beta.readthedocs.com>`_
+
+#. Click on a project name.
+#. Go to **Settings**, then in the left bar, go to  **Addons (Beta)**.
+#. Check **Enable Addons**, or enable Addons individually.

docs/user/analytics.rst

@@ -1,8 +1,7 @@
 How to use traffic analytics
 ============================
 
-In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
-You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
+This guide covers traffic analytics for your documentation project, either built-in or provided through Read the Docs Addons. You can also learn how to enable or disable Google Analytics.
 
 Traffic Analytics lets you see *which* documents your users are reading.
 This allows you to understand how your documentation is being used,
@@ -35,8 +34,8 @@ Enabling Google Analytics on your project
 Read the Docs has native support for Google Analytics.
 You can enable it by:
 
-* Going to :guilabel:`Admin` > :guilabel:`Settings` in your project.
-* Fill in the **Analytics code** heading with your Google Tracking ID (example `UA-123456674-1`)
+#. Going to :guilabel:`Admin` > :guilabel:`Settings` in your project.
+#. Fill in the **Analytics code** heading with your Google Tracking ID (example `UA-123456674-1`)
 
 .. figure:: /_static/images/google-analytics-options.png
    :width: 80%

docs/user/flyout-menu.rst

@@ -8,8 +8,30 @@ you will likely notice that we embed a menu on all the documentation pages we se
 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
--------------
+There are two versions of the flyout menu:
+
+- :ref:`flyout-menu:Addons flyout menu`
+- :ref:`flyout-menu:Original flyout menu`
+
+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.
+
+.. figure:: /_static/images/flyout-addons.png
+   :align: center
+
+   The opened flyout
+
+Customizing the look of the addons flyout menu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+Original flyout menu
+--------------------
 
 The flyout menu provides access to the following bits of Read the Docs functionality:
 
@@ -19,49 +41,34 @@ The flyout menu provides access to the following bits of Read the Docs functiona
 * 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/index` of the current version.
 
-Closed
-~~~~~~
-
-.. figure:: /_static/images/flyout-closed.png
-   :align: center
-
-   The flyout when it's closed
-
-Open
-~~~~
-
 .. figure:: /_static/images/flyout-open.png
    :align: center
 
    The opened flyout
 
 Information for theme authors
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. warning::
 
-   *This is currently deprecated* in favor of the new Read the Docs Addons approach.
-   We are working on an idea that 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.
-
-   We are looking for feedback on this approach before making it public.
-   Please, comment on that PR or the linked issue from its description letting us know if it would cover your use case.
+   The original flyout menu could be themed by injecting code with JavaScript.
+   This approach is currently deprecated* in favor of the new Read the Docs Addons approach.
 
 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[Deprecated] 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 ``<div id="readthedocs-embed-flyout">`` 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 ``<body>``.
 
-Styling the flyout
-~~~~~~~~~~~~~~~~~~
+[Deprecated] 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>`_,

docs/user/index.rst

@@ -22,6 +22,7 @@ Read the Docs: documentation simplified
    /config-file/v2
    /automation-rules
    /guides/reproducible-builds
+   /addons
 
 .. toctree::
    :maxdepth: 2
@@ -62,6 +63,7 @@ Read the Docs: documentation simplified
    /server-side-search/index
    /server-side-search/syntax
    /flyout-menu
+   /notifications
 
 .. toctree::
    :maxdepth: 2

docs/user/notifications.rst

@@ -0,0 +1,14 @@
+Notifications
+=============
+
+As part of the new :doc:`addons`, Read the Docs displays notifications in the following situations:
+
+Pull request notification
+    This notification warns users letting them know the documentation page they are reading comes from a pull request to clearly distinguish this version from the official one.
+
+Non-stable notification
+    A notification on all non-stable versions is shown to clearly communicate to readers they may be reading an outdated version of the documentation.
+
+Latest version notification
+    A notification shown on the latest version tells readers they are reading the latest/development version of the documentation that may include features not yet deployed.
+

docs/user/pull-requests.rst

@@ -24,11 +24,19 @@ Build status report
 
        GitHub build status reporting
 
-Warning banner
-    A warning banner is shown at the top of documentation pages
+Pull request banner
+    A pull request banner is shown at the top of documentation pages
     to let readers know that this version isn't the main version for the project.
 
-    .. note:: Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>`.
+    .. note:: Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>` or projects using :doc:`Read the Docs Addons </addons>`.
+
+DocDiff
+    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.
+
+    .. note:: DocDiff is available only for projects using :doc:`Read the Docs Addons </addons>`.
+
 
 .. seealso::
 

docs/user/server-side-search/index.rst

@@ -6,6 +6,9 @@ this is powered by Elasticsearch_.
 You can search all projects at https://readthedocs.org/search/,
 or search only on your project from the :guilabel:`Search` tab of your project.
 
+If you're using :doc:`/addons`, you also get :ref:`server-side-search/index:search as you type` built in,
+either from the :doc:`/flyout-menu` or from the :guilabel:`Search` tab of your project
+
 .. seealso::
 
    :doc:`/server-side-search/syntax`