Add minimal viable docs for addons (#11444)

* POC addons listing * Remove whitespace with pre-commit * List all addons * Review feedback * Update image * Delete deprecated sections * Restore useful GA section * Tweak wording * Address review feedback
readthedocs · Jul 9, 2024 · 6aaa330 · 6aaa330
1 parent 539f010
commit 6aaa330
Show file tree

Hide file tree

Showing 14 changed files with 126 additions and 221 deletions.
diff --git a/docs/user/_static/images/addons-analytics.png b/docs/user/_static/images/addons-analytics.png
diff --git a/docs/user/_static/images/flyout-addons.png b/docs/user/_static/images/flyout-addons.png
diff --git a/docs/user/_static/images/flyout-closed.png b/docs/user/_static/images/flyout-closed.png
diff --git a/docs/user/_static/images/traffic-analytics-demo.png b/docs/user/_static/images/traffic-analytics-demo.png
diff --git a/docs/user/addons.rst b/docs/user/addons.rst
@@ -0,0 +1,57 @@
+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>`
+    explore pageviews for your docs
+
+:doc:`DocDiff </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
+
+:doc:`Flyout </flyout-menu>`
+    easily switch between versions and translations
+
+:doc:`Non-stable notification </versions>`
+    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
+
+:doc:`Search as you type </server-side-search/index>`
+    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 (Beta)`.
+#. Check :guilabel:`Enable Addons`, and then configure each Addon individually.
+
+.. note::
+
+    Read the Docs Addons will be enabled by default for all Read the Docs projects some time in the second half of 2024.
+
+Configuring Read the Docs Addons
+--------------------------------
+
+Individual configuration options for each addon are available in :guilabel:`Settings`.
+
+#. 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 (Beta)`.
+#. Configure each Addon individually.
diff --git a/docs/user/advertising/advertising-details.rst b/docs/user/advertising/advertising-details.rst
@@ -118,15 +118,12 @@ and we try to respect the different viewpoints as much as possible while also ac
 our own goals.
 
 We have taken steps to address some of the privacy concerns surrounding GA.
-These steps apply both to analytics collected by Read the Docs and when
-:ref:`authors enable analytics on their docs <analytics:Enabling Google Analytics on your Project>`.
+These steps apply to analytics only collected by Read the Docs,
+since project authors could follow a different policy if they add GA to their projects.
 
 * Users can opt-out of analytics by using the Do Not Track feature of their browser.
 * Read the Docs instructs Google to anonymize IP addresses sent to them.
 * The cookie set by GA is a session (non-persistent) cookie rather than the default 2 years.
-* Project maintainers can completely disable analytics on their own projects.
-  Follow the steps in :ref:`analytics:Disabling Google Analytics on your project`.
-
 
 Why we use analytics
 ~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/user/analytics.rst b/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 provided through Read the Docs Addons.
 
 Traffic Analytics lets you see *which* documents your users are reading.
 This allows you to understand how your documentation is being used,
@@ -12,7 +11,7 @@ To see a list of the top pages from the last month,
 go to the :guilabel:`Admin` tab of your project,
 and then click on :guilabel:`Traffic Analytics`.
 
-.. figure:: /_static/images/traffic-analytics-demo.png
+.. figure:: /_static/images/addons-analytics.png
    :width: 50%
    :align: center
    :alt: Traffic analytics demo
@@ -28,44 +27,3 @@ You can also access analytics data from :doc:`search results </guides/search-ana
    * On the Community site, the last 90 days are stored.
    * On the Commercial one, it goes from 30 to infinite storage
       (check out `the pricing page <https://readthedocs.com/pricing/>`_).
-
-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`)
-
-.. figure:: /_static/images/google-analytics-options.png
-   :width: 80%
-   :align: center
-   :alt: Options to manage Google Analytics
-
-   Options to manage Google Analytics
-
-Once your documentation rebuilds it will include your Analytics tracking code and start sending data.
-Google Analytics usually takes 60 minutes,
-and sometimes can take up to a day before it starts reporting data.
-
-.. note::
-
-   Read the Docs takes some extra precautions with analytics to protect user privacy.
-   As a result, users with Do Not Track enabled will not be counted
-   for the purpose of analytics.
-
-   For more details, see the
-   :ref:`Do Not Track section <privacy-policy:Do Not Track>`
-   of our privacy policy.
-
-Disabling Google Analytics on your project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Google Analytics can be completely disabled on your own projects.
-To disable Google Analytics:
-
-* Going to :guilabel:`Admin` > :guilabel:`Settings` in your project.
-* Check the box **Disable Analytics**.
-
-Your documentation will need to be rebuilt for this change to take effect.
diff --git a/docs/user/flyout-menu.rst b/docs/user/flyout-menu.rst
@@ -8,8 +8,40 @@ 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 menu
+
+Customizing the flyout menu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In your dashboard, you can configure flyout menu options in :guilabel:`Settings`, under :guilabel:`Addons (Beta)`.
+
+Sort your versions :guilabel:`Alphabetically`, by :guilabel:`SemVer`, by :guilabel:`Python Packaging`,
+by :guilabel:`CalVer`, or define your own pattern.
+
+Choose whether to list stable versions first or not.
+
+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,140 +51,7 @@ 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.
-
-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 ``<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
-~~~~~~~~~~~~~~~~~~
-
-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.
-
-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">
-             <!-- "Languages" section (``dl`` tag) is not included if the project does not have translations -->
-             <dl>
-                <dt>Languages</dt>
-                <dd class="rtd-current-item">
-                   <a href="https://flask.palletsproject.com/en/2.1.x">en</a>
-                </dd>
-                <dd>
-                   <a href="https://flask.palletsproject.com/es/2.1.x">es</a>
-                </dd>
-             </dl>
-
-             <!-- "Versions" section (``dl`` tag) is not included if the project is single version -->
-             <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>
-
-             <!-- "Downloads" section (``dl`` tag) is not included if the project does not have artifacts to download -->
-             <dl>
-                <dt>Downloads</dt>
-                <dd>
-                   <a href="//flask.palletsprojects.com/_/downloads/en/2.1.x/pdf/">PDF</a>
-                 </dd>
-                <dd>
-                   <a href="//flask.palletsprojects.com/_/downloads/en/2.1.x/htmlzip/">HTML</a>
-                 </dd>
-             </dl>
-
-             <dl>
-                <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> &middot; </span>
-             <a href="https://docs.readthedocs.io/page/privacy-policy.html">Privacy Policy</a>
-             </small>
-          </div>
-       </div>
-    </div>
diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst
@@ -319,7 +319,8 @@ Some of the most valuable feedback these provide include:
 Analytics tools
 ~~~~~~~~~~~~~~~
 
-A tool like :ref:`Google Analytics <analytics:Enabling Google Analytics on your Project>`
+A tool like Google Analytics,
+along with our :doc:`integrated Read the Docs analytics </analytics>`,
 can give you feedback about the search terms people use to find your docs,
 your most popular pages, and lots of other useful data.
 

diff --git a/docs/user/index.rst b/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

diff --git a/docs/user/pull-requests.rst b/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
-    to let readers know that this version isn't the main version for the project.
+Pull request banner
+    A pull request banner is shown at the top of documentation pages
+    to let readers know they aren't viewing an active version of the project.
+
+    .. note:: Warning banners are available only for 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>`.
 
-    .. note:: Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>`.
 
 .. seealso::
 

diff --git a/docs/user/server-side-search/index.rst b/docs/user/server-side-search/index.rst
@@ -80,14 +80,7 @@ Analytics
 Search as you type
 ------------------
 
-`readthedocs-sphinx-search`_ is a Sphinx extension that integrates your
-documentation more closely with the search implementation of Read the Docs.
-It adds a clean and minimal full-page search UI that supports a **search as you type** feature.
+Search as-you-type allows users to quickly find exactly what they are looking for while typing.
+It also saves recent searches, for future reference.
 
-To try this feature,
-you can press :guilabel:`/` (forward slash) and start typing or just visit these URLs:
-
-- https://docs.readthedocs.io/?rtd_search=contributing
-- https://docs.readthedocs.io/?rtd_search=api/v3/projects/
-
-.. _readthedocs-sphinx-search: https://readthedocs-sphinx-search.readthedocs.io/
+Try it by pressing :guilabel:`/` (forward slash) and typing.
diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst
@@ -547,15 +547,6 @@ You can also download this data in :abbr:`CSV (Comma-Separated Values)`  format
 To do that, scroll to the bottom of the page
 and click the :guilabel:`Download all data` button.
 
-.. note::
-
-   You can get more detailed traffic data by
-   :ref:`enabling Google Analytics <analytics:Enabling Google Analytics on your Project>`.
-   Notice though that Read the Docs takes extra measures to :ref:`respect user
-   privacy <advertising/advertising-details:analytics>`
-   when they visit projects that have Google Analytics enabled,
-   which might reduce the number of visits counted.
-
 Understanding search analytics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~