diff --git a/docs/_static/images/google-analytics-options.png b/docs/_static/images/google-analytics-options.png new file mode 100644 index 00000000000..2f869c955ee Binary files /dev/null and b/docs/_static/images/google-analytics-options.png differ diff --git a/docs/_static/images/tutorial/search-analytics-terms.png b/docs/_static/images/tutorial/search-analytics-terms.png new file mode 100644 index 00000000000..28c0e80cfed Binary files /dev/null and b/docs/_static/images/tutorial/search-analytics-terms.png differ diff --git a/docs/_static/images/tutorial/traffic-analytics-plot.png b/docs/_static/images/tutorial/traffic-analytics-plot.png new file mode 100644 index 00000000000..839b1e70240 Binary files /dev/null and b/docs/_static/images/tutorial/traffic-analytics-plot.png differ diff --git a/docs/analytics.rst b/docs/analytics.rst index 8fb791003ee..0762dddb206 100644 --- a/docs/analytics.rst +++ b/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 `. +You can also access to analytics data from :ref:`search results `. + +.. 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 `_). 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. diff --git a/docs/builds.rst b/docs/builds.rst index b1aa93d9c0c..6fb03a27ea0 100644 --- a/docs/builds.rst +++ b/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 `_. `Docker Hub `_ also shows the latest set of images that have been built. -.. _default-versions: - Default versions of dependencies -------------------------------- diff --git a/docs/conf.py b/docs/conf.py index dfcbc29900e..2740d085d3e 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/server-side-search.rst b/docs/server-side-search.rst index c091db4ea20..87bbc285568 100644 --- a/docs/server-side-search.rst +++ b/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, diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index ba146b8b246..de1bf3e82f8 100644 --- a/docs/tutorial/index.rst +++ b/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 ` 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 `. +by :ref:`making some decisions on your behalf `. 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 `. -``python.version`` +``build.os`` + Required to specify the Python version, + :ref:`states the name of the base image `. + +``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 `. + Notice though that we take some extra measures to :ref:`respect user + privacy ` + 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 ` +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 ` + or the `MkDocs 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 ` + (and if in doubt, check out :doc:`/choosing-a-site`). +- Do you want to join a global community of fellow `documentarians `? + Check out `Write the Docs `_ and + :doc:`its Slack workspace `. +- Do you want to :doc:`contribute to Read the Docs `? + We greatly appreciate it! Check out :doc:`/development/docs`. + +Happy documenting!