diff --git a/docs/user/_static/images/addons-analytics.png b/docs/user/_static/images/addons-analytics.png new file mode 100644 index 00000000000..6c4809c4120 Binary files /dev/null and b/docs/user/_static/images/addons-analytics.png differ diff --git a/docs/user/_static/images/flyout-addons.png b/docs/user/_static/images/flyout-addons.png new file mode 100644 index 00000000000..216019188d5 Binary files /dev/null and b/docs/user/_static/images/flyout-addons.png differ diff --git a/docs/user/_static/images/flyout-closed.png b/docs/user/_static/images/flyout-closed.png deleted file mode 100644 index d5bf7b5e5ba..00000000000 Binary files a/docs/user/_static/images/flyout-closed.png and /dev/null differ diff --git a/docs/user/_static/images/traffic-analytics-demo.png b/docs/user/_static/images/traffic-analytics-demo.png deleted file mode 100644 index 379e802f82a..00000000000 Binary files a/docs/user/_static/images/traffic-analytics-demo.png and /dev/null differ diff --git a/docs/user/addons.rst b/docs/user/addons.rst new file mode 100644 index 00000000000..dff978bf8c1 --- /dev/null +++ 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 ` + explore pageviews for your docs + +:doc:`DocDiff ` + highlight changed output from pull requests + +:doc:`Pull request notification ` + notify readers that they are reading docs from a pull request + +:doc:`Flyout ` + easily switch between versions and translations + +:doc:`Non-stable notification ` + notify readers that they are reading docs from a non stable release + +:doc:`Latest version notification ` + notify readers that they are reading docs from a development version + +:doc:`Search as you type ` + get search results faster + +Enabling Read the Docs Addons +----------------------------- + +All projects using ``mkdocs`` :ref:`mkdocs ` or the ``build.command`` :ref:`build command ` are already using the Addons, other projects can enable them by following these steps: + +#. Go to the new dashboard: + + * `Community `_ + * `Business `_ + +#. 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 `_ + * `Business `_ + +#. 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 index 93a4d7571c6..b0cc218d723 100644 --- 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 `. +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 index 6d5f01f21d1..314999b3717 100644 --- 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 `_). - -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 ` - 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 index 6bac7516fae..37b27a394a8 100644 --- 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 ` 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 ``
`` 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 - - -
- -
-
Languages
-
- en -
-
- es -
-
- - -
-
Versions
-
- latest -
-
- 2.1.x -
-
- - -
-
Downloads
-
- PDF -
-
- HTML -
-
- -
-
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/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index d8614e36140..a8f1f7e7a5a 100644 --- 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 ` +A tool like Google Analytics, +along with our :doc:`integrated Read the Docs 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 index 685b997887e..2ef18262d80 100644 --- 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 index 3590d64dd3d..6bde044a54d 100644 --- 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 `. + +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 `. - .. note:: Warning banners are available only for :doc:`Sphinx projects `. .. seealso:: diff --git a/docs/user/server-side-search/index.rst b/docs/user/server-side-search/index.rst index 7bffda91c15..36df7b3aa05 100644 --- 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 index 51880c44910..206d78d90fe 100644 --- 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 `. - Notice though that Read the Docs takes extra measures to :ref:`respect user - privacy ` - when they visit projects that have Google Analytics enabled, - which might reduce the number of visits counted. - Understanding search analytics ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/user/versions.rst b/docs/user/versions.rst index 6faa1c14668..b6837432695 100644 --- a/docs/user/versions.rst +++ b/docs/user/versions.rst @@ -1,7 +1,7 @@ Versions ======== -Read the Docs supports multiple versions of your repository. +Read the Docs supports multiple versions of your documentation. On initial import, we will create a ``latest`` version. This will point at the default branch defined in your Git repository. @@ -136,24 +136,24 @@ tags will take preference over branches when selecting the stable version. Version warning --------------- -A banner can be automatically displayed to notify viewers that there may be -a more stable version of the documentation available. Specifically: +As part of the new :doc:`addons`, Read the Docs displays notifications in the following situations: -- When the ``latest`` version is being shown, and there's also a ``stable`` version active and not hidden, - then the banner will remind the viewer that some of the documented features may not yet be - available, and suggest that the viewer switch to the ``stable`` version. -- When a version is being shown that is not the ``stable`` version, and there's a ``stable`` - version available, then the banner will suggest that the viewer switch to the ``stable`` version - to see the newest documentation. +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. + Specifically, when a version is being shown that is not the ``stable`` version, and there is a ``stable`` + version available. -This feature is enabled by default on projects using the new beta addons. -The beta addons can be enabled by using ``build.commands`` config key or via the new beta dashboard (https://app.readthedocs.org) going to the admin section of your docs (:guilabel:`Settings` > :guilabel:`Addons (Beta)`) +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. + + Specically, when the ``latest`` version is being shown, and there's also an active ``stable`` version that is not hidden. + +Each of these notifcations can be configured by project admins in :ref:`addons:Configuring Read the Docs Addons` .. note:: - An older version of this feature is currently only available to projects that have already enabled it. - When the updated feature development is finished the toggle setting will be enabled for all projects. + An older version of these warning banners is only available to projects that had enabled it before the release of :doc:`addons`. Redirects on root URLs ----------------------