New Read the Docs tutorial, part III (and finale?)

docs/analytics.rst

@@ -16,7 +16,15 @@ and then click on :guilabel:`Traffic Analytics`.
 
    Traffic analytics demo
 
-You can also access to analytics data from :ref:`search results <server-side-search:analytics>`.
+You can also access to analytics data from :ref:`search results <server-side-search:Search Analytics>`.
+
+.. note::
+
+   The amount of analytics data stored for download depends which site you're using:
+
+   * 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
 -----------------------------------------
@@ -27,6 +35,13 @@ You can enable it by:
 * Going to :guilabel:`Admin` > :guilabel:`Advanced 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.

docs/builds.rst

@@ -102,8 +102,6 @@ but you can change that using a :doc:`/config-file/index`.
 You can see the current Docker build images that we use in our `docker repository <https://github.com/readthedocs/readthedocs-docker-images>`_.
 `Docker Hub <https://hub.docker.com/r/readthedocs/build/>`_ also shows the latest set of images that have been built.
 
-.. _default-versions:
-
 Default versions of dependencies
 --------------------------------
 

docs/conf.py

@@ -61,6 +61,7 @@ def get_version():
     'poliastro': ('https://docs.poliastro.space/en/v0.15.2/', None),
     'qiskit': ('https://qiskit.org/documentation/', None),
     'myst-parser': ('https://myst-parser.readthedocs.io/en/v0.15.1/', None),
+    'writethedocs': ('https://www.writethedocs.org/', None),
 }
 hoverxref_intersphinx = [
    "sphinx",

docs/server-side-search.rst

@@ -52,8 +52,8 @@ Configurable.
 
 .. _"full-text search": https://docs.readthedocs.io/en/latest/search.html?q=%22full-text+search%22
 
-Analytics
----------
+Search Analytics
+----------------
 
 Know what your users are looking for in your docs.
 To see a list of the top queries and an overview from the last month,

docs/tutorial/index.rst

@@ -173,7 +173,7 @@ Checking the first build
 Read the Docs will try to build the documentation of your project
 right after you create it.
 To see the build logs,
-click on the "Your documentation is building" link on the :term:`project home`,
+click on the :guilabel:`Your documentation is building` link on the :term:`project home`,
 or alternatively navigate to the "Builds" page,
 then open the one on top (the most recent one).
 
@@ -191,7 +191,7 @@ meaning that it is still in progress.
 When the build finishes, you will see a green "Build completed" indicator,
 the completion date, the elapsed time,
 and a link to see the corresponding documentation.
-If you now click on "View docs", you will see your documentation live!
+If you now click on :guilabel:`View docs`, you will see your documentation live!
 
 .. figure:: /_static/images/tutorial/rtd-first-light.png
    :width: 80%
@@ -217,7 +217,7 @@ Basic configuration changes
 
 You can now proceed to make some basic configuration adjustments.
 Navigate back to the :term:`project page`
-and click on the "⚙ Admin" button, which will open the Settings page.
+and click on the :guilabel:`⚙ Admin` button, which will open the Settings page.
 
 First of all, add the following text in the description:
 
@@ -229,9 +229,9 @@ and write ``food, python`` in the list of tags.
 All this information will be shown on your project home.
 
 After that, configure your email so you get a notification if the build fails.
-To do so, click on the "Notifications" link on the left,
+To do so, click on the :guilabel:`Notifications` link on the left,
 type the email where you would like to get the notification,
-and click the "Add" button.
+and click the :guilabel:`Add` button.
 After that, your email will be shown under "Existing Notifications".
 
 Trigger a build from a pull request
@@ -240,8 +240,8 @@ Trigger a build from a pull request
 Read the Docs allows you to :doc:`trigger builds from GitHub pull requests </pull-requests>`
 and gives you a preview of how the documentation would look like with those changes.
 
-To enable that functionality, first click on the "Advanced Settings" link on the left
-under the "⚙ Admin" menu, check the "Build pull requests for this project" checkbox,
+To enable that functionality, first click on the :guilabel:`Advanced Settings` link on the left
+under the :guilabel:`⚙ Admin` menu, check the "Build pull requests for this project" checkbox,
 and click the :guilabel:`Save` button at the bottom of the page.
 
 Next, navigate to your GitHub repository, locate the file ``docs/source/index.rst``,
@@ -280,7 +280,7 @@ and there click the :guilabel:`Create pull request` button below the description
 
 After opening the pull request, a Read the Docs check will appear
 indicating that it is building the documentation for that pull request.
-If you click on the "Details" link while it is building,
+If you click on the :guilabel:`Details` link while it is building,
 you will access the build logs,
 otherwise it will take you directly to the documentation.
 When you are satisfied, you can merge the pull request!
@@ -299,7 +299,7 @@ This has several advantages:
 - Some configurations are only available using the config file.
 
 Read the Docs works without this configuration
-by :ref:`making some decisions on your behalf <default-versions>`.
+by :ref:`making some decisions on your behalf <builds:Default versions of dependencies>`.
 For example, what Python version to use, how to install the requirements, and others.
 
 .. tip::
@@ -319,15 +319,21 @@ and add a ``.readthedocs.yaml`` file with these contents to the root of your pro
 
    version: 2
 
-   python:
-     version: "3.8"
+   build:
+     os: "ubuntu-20.04"
+     tools:
+       python: "3.8"
 
 The purpose of each key is:
 
 ``version``
   Mandatory, specifies :doc:`version 2 of the configuration file </config-file/v2>`.
 
-``python.version``
+``build.os``
+  Required to specify the Python version,
+  :ref:`states the name of the base image <config-file/v2:build.os>`.
+
+``build.tools.python``
   Declares the Python version to be used.
 
 After you commit these changes, go back to your project home,
@@ -352,7 +358,7 @@ but actually the API section is empty.
 This is a very common issue with Sphinx,
 and the reason is stated in the build logs.
 On the build page you opened before,
-click on the "View raw" text on the top right,
+click on the :guilabel:`View raw` link on the top right,
 which opens the build logs in plain text,
 and you will see several warnings:
 
@@ -460,7 +466,7 @@ type ``1.0.x``, and click on "Create branch: 1.0.x from 'main'"
 
 __  https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository
 
-Next, go to your :term:`project home`, click on the "Versions" button,
+Next, go to your :term:`project home`, click on the :guilabel:`Versions` button,
 and under "Active Versions" you will see two entries:
 
 - The ``latest`` version, pointing to the ``main`` branch.
@@ -492,7 +498,8 @@ so that users see the ``stable`` documentation
 when they visit the :term:`root URL` of your documentation
 (while still being able to change the version in the flyout menu).
 
-For that, go to the "Advanced Settings" link under the "⚙ Admin" menu of your project home,
+For that, go to the :guilabel:`Advanced Settings` link
+under the :guilabel:`⚙ Admin` menu of your project home,
 choose ``stable`` in the "Default version*" dropdown,
 and hit :guilabel:`Save` at the bottom.
 Done!
@@ -545,8 +552,8 @@ This will trigger two things:
 - Since you already have an active ``stable`` version, ``2.0.x`` will be activated.
 
 From this point, ``1.0.x`` version is no longer the most up to date one.
-To display a warning to your readers, go to the "⚙ Admin" menu of your project home,
-click on the "Advanced Settings" link on the left,
+To display a warning to your readers, go to the :guilabel:`⚙ Admin` menu of your project home,
+click on the :guilabel:`Advanced Settings` link on the left,
 enable the "Show version warning" checkbox, and click the :guilabel:`Save` button.
 
 If you now browse the ``1.0.x`` documentation, you will see a warning on top
@@ -559,7 +566,120 @@ encouraging you to browse the latest version instead. Neat!
 
    Warning for old versions
 
-----
+Getting insights from your projects
+-----------------------------------
+
+Once your project is up and running, you will probably want to understand
+how readers are using your documentation, addressing some common questions like:
+
+- what pages are the most visited pages?
+- what search terms are the most frequently used?
+- are readers finding what they look for?
 
-That's the end of the tutorial,
-but you can learn more about the platform starting with our :doc:`/features` page.
+Read the Docs offers you some analytics tools to find out the answers.
+
+Browsing Traffic Analytics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :doc:`/analytics` view shows the top viewed documentation pages of the past 30 days,
+plus a visualization of the daily views during that period.
+To generate some artificial views on your newly created project,
+you can first click around the different pages of your project,
+which will be accounted immediately for the current day statistics.
+
+To see the Traffic Analytics view, go back the :term:`project page` again,
+click on the :guilabel:`⚙ Admin` button,
+and then click on the :guilabel:`Traffic Analytics` section.
+You will see the list of pages in descending order of visits,
+as well as a plot similar to the one below.
+
+.. figure:: /_static/images/tutorial/traffic-analytics-plot.png
+   :width: 80%
+   :align: center
+   :alt: Traffic Analytics plot
+
+   Traffic Analytics plot
+
+.. note::
+
+   The Traffic Analytics view explained above gives you a simple overview
+   of how your readers browse your documentation. It has the advantage that
+   it stores no identifying information about your visitors,
+   and therefore it respects their privacy.
+   However, you might want to get more detailed data by
+   :ref:`enabling Google Analytics <analytics:Enabling Google Analytics on your Project>`.
+   Notice though that we take some extra measures to :ref:`respect user
+   privacy <advertising/advertising-details:analytics>`
+   when they visit projects that have Google Analytics enabled,
+   and this might reduce the number of visits counted.
+
+Finally, you can also download this data for closer inspection.
+To do that, scroll to the bottom of the page
+and click on the :guilabel:`Download all data` button.
+That will prompt you to download a :abbr:`CSV (Comma-Separated Values)` file
+that you can process any way you want.
+
+Browsing Search Analytics
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Apart from traffic analytics, Read the Docs also offers the possibility
+to inspect :ref:`what search terms your readers use <server-side-search:Search Analytics>`
+on your documentation.
+This can inform decisions on what areas to reinforce,
+or what parts of your project are less understood or more difficult to find.
+
+To generate some artificial search statistics on the project,
+go to the HTML documentation, locate the Sphinx search box on the left,
+type ``ingredients``, and press the :kbd:`Enter` key.
+You will be redirected to the search results page, which will show two entries.
+
+Next, go back to the :guilabel:`⚙ Admin` section of your project page,
+and then click on the :guilabel:`Search Analytics` section.
+You will see a table with the most searched queries
+(including the ``ingredients`` one you just typed),
+how many results did each query return, and how many times it was searched.
+Below the queries table, you will also see a visualization
+of the daily number of search queries during the past 30 days.
+
+.. figure:: /_static/images/tutorial/search-analytics-terms.png
+   :width: 80%
+   :align: center
+   :alt: Most searched terms
+
+   Most searched terms
+
+Like the Traffic Analytics, you can also download the whole dataset in CSV format
+by clicking on the :guilabel:`Download all data` button.
+
+Where to go from here
+---------------------
+
+This is the end of the tutorial. You started by forking a GitHub repository
+and importing it on Read the Docs, building its HTML documentation,
+and then went through a series of steps to customize the build process,
+tweak the project configuration, and add new versions.
+
+Here you have some resources to continue learning about documentation
+and Read the Docs:
+
+- You can learn more about the functionality of the platform
+  by going over our :doc:`/features` page.
+- To make the most of the documentation generators that are supported,
+  you can read the :doc:`Sphinx tutorial <sphinx:tutorial/index>`
+  or the `MkDocs User Guide <https://www.mkdocs.org/user-guide/>`_.
+- Whether you are a documentation author, a project administrator, a developer, or a designer,
+  you can follow our how-to guides that cover specific tasks,
+  available under :doc:`/guides/index`.
+- You can check out some of the
+  :ref:`index:Advanced features of Read the Docs`,
+  like :doc:`/subprojects` or :doc:`/automation-rules`, to name a few.
+- For private project support and other enterprise features,
+  you can use :doc:`our commercial service </commercial/index>`
+  (and if in doubt, check out :doc:`/choosing-a-site`).
+- Do you want to join a global community of fellow `documentarians <writethedocs:documentarians>`?
+  Check out `Write the Docs <https://www.writethedocs.org/>`_ and
+  :doc:`its Slack workspace <writethedocs:slack>`.
+- Do you want to :doc:`contribute to Read the Docs </contribute>`?
+  We greatly appreciate it! Check out :doc:`/development/docs`.
+
+Happy documenting!