Skip to content

Commit 6aaa330

Browse files
plaindocsplaindocs
authored
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
1 parent 539f010 commit 6aaa330

14 files changed

+126
-221
lines changed

‎docs/user/_static/images/addons-analytics.png

34.6 KB
Loading

‎docs/user/_static/images/flyout-addons.png

29.5 KB
Loading

‎docs/user/_static/images/flyout-closed.png

-5.98 KB
Binary file not shown.

‎docs/user/_static/images/traffic-analytics-demo.png

-234 KB
Binary file not shown.

‎docs/user/addons.rst

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
Read the Docs Addons
2+
====================
3+
4+
**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:
5+
6+
:doc:`Traffic analytics </analytics>`
7+
explore pageviews for your docs
8+
9+
:doc:`DocDiff </pull-requests>`
10+
highlight changed output from pull requests
11+
12+
:doc:`Pull request notification </pull-requests>`
13+
notify readers that they are reading docs from a pull request
14+
15+
:doc:`Flyout </flyout-menu>`
16+
easily switch between versions and translations
17+
18+
:doc:`Non-stable notification </versions>`
19+
notify readers that they are reading docs from a non stable release
20+
21+
:doc:`Latest version notification </versions>`
22+
notify readers that they are reading docs from a development version
23+
24+
:doc:`Search as you type </server-side-search/index>`
25+
get search results faster
26+
27+
Enabling Read the Docs Addons
28+
-----------------------------
29+
30+
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:
31+
32+
#. Go to the new dashboard:
33+
34+
* `Community <https://app.readthedocs.org>`_
35+
* `Business <https://app.readthedocs.com>`_
36+
37+
#. Click on a project name.
38+
#. Go to :guilabel:`Settings`, then in the left bar, go to :guilabel:`Addons (Beta)`.
39+
#. Check :guilabel:`Enable Addons`, and then configure each Addon individually.
40+
41+
.. note::
42+
43+
Read the Docs Addons will be enabled by default for all Read the Docs projects some time in the second half of 2024.
44+
45+
Configuring Read the Docs Addons
46+
--------------------------------
47+
48+
Individual configuration options for each addon are available in :guilabel:`Settings`.
49+
50+
#. Go to the new dashboard:
51+
52+
* `Community <https://app.readthedocs.org>`_
53+
* `Business <https://app.readthedocs.com>`_
54+
55+
#. Click on a project name.
56+
#. Go to :guilabel:`Settings`, then in the left bar, go to :guilabel:`Addons (Beta)`.
57+
#. Configure each Addon individually.

‎docs/user/advertising/advertising-details.rst

+2-5
Original file line numberDiff line numberDiff line change
@@ -118,15 +118,12 @@ and we try to respect the different viewpoints as much as possible while also ac
118118
our own goals.
119119

120120
We have taken steps to address some of the privacy concerns surrounding GA.
121-
These steps apply both to analytics collected by Read the Docs and when
122-
:ref:`authors enable analytics on their docs <analytics:Enabling Google Analytics on your Project>`.
121+
These steps apply to analytics only collected by Read the Docs,
122+
since project authors could follow a different policy if they add GA to their projects.
123123

124124
* Users can opt-out of analytics by using the Do Not Track feature of their browser.
125125
* Read the Docs instructs Google to anonymize IP addresses sent to them.
126126
* The cookie set by GA is a session (non-persistent) cookie rather than the default 2 years.
127-
* Project maintainers can completely disable analytics on their own projects.
128-
Follow the steps in :ref:`analytics:Disabling Google Analytics on your project`.
129-
130127

131128
Why we use analytics
132129
~~~~~~~~~~~~~~~~~~~~

‎docs/user/analytics.rst

+2-44
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
How to use traffic analytics
22
============================
33

4-
In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
5-
You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
4+
This guide covers traffic analytics for your documentation project provided through Read the Docs Addons.
65

76
Traffic Analytics lets you see *which* documents your users are reading.
87
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,
1211
go to the :guilabel:`Admin` tab of your project,
1312
and then click on :guilabel:`Traffic Analytics`.
1413

15-
.. figure:: /_static/images/traffic-analytics-demo.png
14+
.. figure:: /_static/images/addons-analytics.png
1615
:width: 50%
1716
:align: center
1817
:alt: Traffic analytics demo
@@ -28,44 +27,3 @@ You can also access analytics data from :doc:`search results </guides/search-ana
2827
* On the Community site, the last 90 days are stored.
2928
* On the Commercial one, it goes from 30 to infinite storage
3029
(check out `the pricing page <https://readthedocs.com/pricing/>`_).
31-
32-
Enabling Google Analytics on your project
33-
-----------------------------------------
34-
35-
Read the Docs has native support for Google Analytics.
36-
You can enable it by:
37-
38-
* Going to :guilabel:`Admin` > :guilabel:`Settings` in your project.
39-
* Fill in the **Analytics code** heading with your Google Tracking ID (example `UA-123456674-1`)
40-
41-
.. figure:: /_static/images/google-analytics-options.png
42-
:width: 80%
43-
:align: center
44-
:alt: Options to manage Google Analytics
45-
46-
Options to manage Google Analytics
47-
48-
Once your documentation rebuilds it will include your Analytics tracking code and start sending data.
49-
Google Analytics usually takes 60 minutes,
50-
and sometimes can take up to a day before it starts reporting data.
51-
52-
.. note::
53-
54-
Read the Docs takes some extra precautions with analytics to protect user privacy.
55-
As a result, users with Do Not Track enabled will not be counted
56-
for the purpose of analytics.
57-
58-
For more details, see the
59-
:ref:`Do Not Track section <privacy-policy:Do Not Track>`
60-
of our privacy policy.
61-
62-
Disabling Google Analytics on your project
63-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64-
65-
Google Analytics can be completely disabled on your own projects.
66-
To disable Google Analytics:
67-
68-
* Going to :guilabel:`Admin` > :guilabel:`Settings` in your project.
69-
* Check the box **Disable Analytics**.
70-
71-
Your documentation will need to be rebuilt for this change to take effect.

‎docs/user/flyout-menu.rst

+34-135
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,40 @@ you will likely notice that we embed a menu on all the documentation pages we se
88
This is a way to expose the functionality of Read the Docs on the page,
99
without having to have the documentation theme integrate it directly.
1010

11-
Functionality
12-
-------------
11+
There are two versions of the flyout menu:
12+
13+
- :ref:`flyout-menu:Addons flyout menu`
14+
- :ref:`flyout-menu:Original flyout menu`
15+
16+
Addons flyout menu
17+
------------------
18+
19+
The updated :doc:`addons` flyout menu lists available documentation versions and translations, as well as useful links,
20+
offline formats, and a search bar.
21+
22+
.. figure:: /_static/images/flyout-addons.png
23+
:align: center
24+
25+
The opened flyout menu
26+
27+
Customizing the flyout menu
28+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
29+
30+
In your dashboard, you can configure flyout menu options in :guilabel:`Settings`, under :guilabel:`Addons (Beta)`.
31+
32+
Sort your versions :guilabel:`Alphabetically`, by :guilabel:`SemVer`, by :guilabel:`Python Packaging`,
33+
by :guilabel:`CalVer`, or define your own pattern.
34+
35+
Choose whether to list stable versions first or not.
36+
37+
Customizing the look of the addons flyout menu
38+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39+
40+
The addons flyout exposes all the required data to build the flyout menu via a JavaScript ``CustomEvent``.
41+
Take a look at an example of this approach at https://github.com/readthedocs/sphinx_rtd_theme/pull/1526.
42+
43+
Original flyout menu
44+
--------------------
1345

1446
The flyout menu provides access to the following bits of Read the Docs functionality:
1547

@@ -19,140 +51,7 @@ The flyout menu provides access to the following bits of Read the Docs functiona
1951
* Links to your :doc:`VCS provider </integrations>` that allow the user to quickly find the exact file that the documentation was rendered from.
2052
* A search bar that gives users access to our :doc:`/server-side-search/index` of the current version.
2153

22-
Closed
23-
~~~~~~
24-
25-
.. figure:: /_static/images/flyout-closed.png
26-
:align: center
27-
28-
The flyout when it's closed
29-
30-
Open
31-
~~~~
32-
3354
.. figure:: /_static/images/flyout-open.png
3455
:align: center
3556

3657
The opened flyout
37-
38-
Information for theme authors
39-
-----------------------------
40-
41-
.. warning::
42-
43-
*This is currently deprecated* in favor of the new Read the Docs Addons approach.
44-
We are working on an idea that exposes all the required data to build the flyout menu via a JavaScript ``CustomEvent``.
45-
Take a look at an example of this approach at https://github.com/readthedocs/sphinx_rtd_theme/pull/1526.
46-
47-
We are looking for feedback on this approach before making it public.
48-
Please, comment on that PR or the linked issue from its description letting us know if it would cover your use case.
49-
50-
People who are making custom documentation themes often want to specify where the flyout is injected,
51-
and also what it looks like.
52-
We support both of these use cases for themes.
53-
54-
Defining where the flyout menu is injected
55-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56-
57-
The flyout menu injection looks for a specific selector (``#readthedocs-embed-flyout``),
58-
in order to inject the flyout.
59-
You can add ``<div id="readthedocs-embed-flyout">`` in your theme,
60-
and our JavaScript code will inject the flyout there.
61-
All other themes except for the ``sphinx_rtd_theme`` have the flyout appended to the ``<body>``.
62-
63-
Styling the flyout
64-
~~~~~~~~~~~~~~~~~~
65-
66-
HTML themes can style the flyout to make it match the overall style of the HTML.
67-
By default the flyout has it's `own CSS file <https://github.com/readthedocs/sphinx_rtd_theme/blob/master/src/sass/_theme_badge.sass>`_,
68-
which you can look at to see the basic CSS class names.
69-
70-
The example HTML that the flyout uses is included here,
71-
so that you can style it in your HTML theme:
72-
73-
.. code:: html
74-
75-
<div class="injected">
76-
<div class="rst-versions rst-badge shift-up" data-toggle="rst-versions">
77-
<span class="rst-current-version" data-toggle="rst-current-version">
78-
<span class="fa fa-book">&nbsp;</span>
79-
v: 2.1.x
80-
<span class="fa fa-caret-down"></span>
81-
</span>
82-
<div class="rst-other-versions">
83-
<!-- "Languages" section (``dl`` tag) is not included if the project does not have translations -->
84-
<dl>
85-
<dt>Languages</dt>
86-
<dd class="rtd-current-item">
87-
<a href="https://flask.palletsproject.com/en/2.1.x">en</a>
88-
</dd>
89-
<dd>
90-
<a href="https://flask.palletsproject.com/es/2.1.x">es</a>
91-
</dd>
92-
</dl>
93-
94-
<!-- "Versions" section (``dl`` tag) is not included if the project is single version -->
95-
<dl>
96-
<dt>Versions</dt>
97-
<dd>
98-
<a href="https://flask.palletsprojects.com/en/latest/">latest</a>
99-
</dd>
100-
<dd class="rtd-current-item">
101-
<a href="https://flask.palletsprojects.com/en/2.1.x/">2.1.x</a>
102-
</dd>
103-
</dl>
104-
105-
<!-- "Downloads" section (``dl`` tag) is not included if the project does not have artifacts to download -->
106-
<dl>
107-
<dt>Downloads</dt>
108-
<dd>
109-
<a href="//flask.palletsprojects.com/_/downloads/en/2.1.x/pdf/">PDF</a>
110-
</dd>
111-
<dd>
112-
<a href="//flask.palletsprojects.com/_/downloads/en/2.1.x/htmlzip/">HTML</a>
113-
</dd>
114-
</dl>
115-
116-
<dl>
117-
<dt>On Read the Docs</dt>
118-
<dd>
119-
<a href="//readthedocs.org/projects/flask/">Project Home</a>
120-
</dd>
121-
<dd>
122-
<a href="//readthedocs.org/projects/flask/builds/">Builds</a>
123-
</dd>
124-
<dd>
125-
<a href="//readthedocs.org/projects/flask/downloads/">Downloads</a>
126-
</dd>
127-
</dl>
128-
129-
<dl>
130-
<dt>On GitHub</dt>
131-
<dd>
132-
<a href="https://github.com/pallets/flask/blob/2.1.x/docs/index.rst">View</a>
133-
</dd>
134-
<dd>
135-
<a href="https://github.com/pallets/flask/edit/2.1.x/docs/index.rst">Edit</a>
136-
</dd>
137-
</dl>
138-
139-
<dl>
140-
<dt>Search</dt>
141-
<dd>
142-
<div style="padding: 6px;">
143-
<form id="flyout-search-form" class="wy-form" target="_blank" action="//readthedocs.org/projects/flask/search/" method="get">
144-
<input type="text" name="q" aria-label="Search docs" placeholder="Search docs">
145-
</form>
146-
</div>
147-
</dd>
148-
</dl>
149-
150-
<hr>
151-
<small>
152-
<span>Hosted by <a href="https://readthedocs.org">Read the Docs</a></span>
153-
<span> &middot; </span>
154-
<a href="https://docs.readthedocs.io/page/privacy-policy.html">Privacy Policy</a>
155-
</small>
156-
</div>
157-
</div>
158-
</div>

‎docs/user/guides/technical-docs-seo-guide.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -319,7 +319,8 @@ Some of the most valuable feedback these provide include:
319319
Analytics tools
320320
~~~~~~~~~~~~~~~
321321

322-
A tool like :ref:`Google Analytics <analytics:Enabling Google Analytics on your Project>`
322+
A tool like Google Analytics,
323+
along with our :doc:`integrated Read the Docs analytics </analytics>`,
323324
can give you feedback about the search terms people use to find your docs,
324325
your most popular pages, and lots of other useful data.
325326

‎docs/user/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Read the Docs: documentation simplified
2222
/config-file/v2
2323
/automation-rules
2424
/guides/reproducible-builds
25+
/addons
2526

2627
.. toctree::
2728
:maxdepth: 2

‎docs/user/pull-requests.rst

+12-4
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,19 @@ Build status report
2424

2525
GitHub build status reporting
2626

27-
Warning banner
28-
A warning banner is shown at the top of documentation pages
29-
to let readers know that this version isn't the main version for the project.
27+
Pull request banner
28+
A pull request banner is shown at the top of documentation pages
29+
to let readers know they aren't viewing an active version of the project.
30+
31+
.. note:: Warning banners are available only for projects using :doc:`Read the Docs Addons </addons>`.
32+
33+
DocDiff
34+
DocDiff shows proposed changes by visually highlighting the differences between the current pull request and the latest version of the project's documentation.
35+
36+
Press ``d`` to toggle between DocDiff and normal pull request preview.
37+
38+
.. note:: DocDiff is available only for projects using :doc:`Read the Docs Addons </addons>`.
3039

31-
.. note:: Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>`.
3240

3341
.. seealso::
3442

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

+3-10
Original file line numberDiff line numberDiff line change
@@ -80,14 +80,7 @@ Analytics
8080
Search as you type
8181
------------------
8282

83-
`readthedocs-sphinx-search`_ is a Sphinx extension that integrates your
84-
documentation more closely with the search implementation of Read the Docs.
85-
It adds a clean and minimal full-page search UI that supports a **search as you type** feature.
83+
Search as-you-type allows users to quickly find exactly what they are looking for while typing.
84+
It also saves recent searches, for future reference.
8685

87-
To try this feature,
88-
you can press :guilabel:`/` (forward slash) and start typing or just visit these URLs:
89-
90-
- https://docs.readthedocs.io/?rtd_search=contributing
91-
- https://docs.readthedocs.io/?rtd_search=api/v3/projects/
92-
93-
.. _readthedocs-sphinx-search: https://readthedocs-sphinx-search.readthedocs.io/
86+
Try it by pressing :guilabel:`/` (forward slash) and typing.

‎docs/user/tutorial/index.rst

-9
Original file line numberDiff line numberDiff line change
@@ -547,15 +547,6 @@ You can also download this data in :abbr:`CSV (Comma-Separated Values)` format
547547
To do that, scroll to the bottom of the page
548548
and click the :guilabel:`Download all data` button.
549549

550-
.. note::
551-
552-
You can get more detailed traffic data by
553-
:ref:`enabling Google Analytics <analytics:Enabling Google Analytics on your Project>`.
554-
Notice though that Read the Docs takes extra measures to :ref:`respect user
555-
privacy <advertising/advertising-details:analytics>`
556-
when they visit projects that have Google Analytics enabled,
557-
which might reduce the number of visits counted.
558-
559550
Understanding search analytics
560551
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
561552

0 commit comments

Comments
 (0)