Docs: update tutorial with the latest required changes

docs/user/tutorial/index.rst

@@ -38,6 +38,10 @@ which will generate a new repository on your personal account
 This is the repository you will import on Read the Docs,
 and it contains the following files:
 
+``.readthedocs.yaml``
+  Read the Docs configuration file.
+  Required to setup the documentation build process.
+
 ``README.rst``
   Basic description of the repository, you will leave it untouched.
 
@@ -147,15 +151,9 @@ Name
 Repository URL
   The URL that contains the sources. Leave the automatically filled value.
 
-Repository type
-  Version control system used, leave it as "Git".
-
 Default branch
   Name of the default branch of the project, leave it as ``main``.
 
-Edit advanced project options
-  Leave it unchecked, we will make some changes later.
-
 After hitting the :guilabel:`Next` button, you will be redirected to the :term:`project home`.
 You just created your first project on Read the Docs! |:tada:|
 
@@ -287,13 +285,7 @@ When you are satisfied, you can merge the pull request!
 Adding a configuration file
 ---------------------------
 
-As of September 2023,
-:doc:`you will need to add a configuration file to build your documentation <rtd-blog:migrate-configuration-v2>`.
-Until then,
-this example project will build without the configuration file,
-but we **strongly recommend** completing this section in order to add a configuration file.
-
-The Settings page of the :term:`project home` allows you
+The Admin tab of the :term:`project home` allows you
 to change some *global* configuration values of your project.
 In addition, you can further customize the building process
 using the ``.readthedocs.yaml`` :doc:`configuration file </config-file/v2>`.
@@ -316,23 +308,28 @@ In this section, we will show you some examples of what a configuration file sho
    Settings that apply to the entire project are controlled in the web dashboard,
    while settings that are version or build specific are better in the YAML file.
 
-Upgrading the Python version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Changing the Python version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For example, to explicitly use Python 3.8 to build your project,
-navigate to your GitHub repository, click on the :guilabel:`Add file` button,
-and add a ``.readthedocs.yaml`` file with these contents to the root of your project:
+navigate to your GitHub repository, click on ``.readthedocs.yaml`` file and then in the pencil icon ✏️ to edit the file
+and change the Python version as follows:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
+   :emphasize-lines: 6
 
    version: 2
 
    build:
-     os: "ubuntu-20.04"
+     os: "ubuntu-22.04"
      tools:
        python: "3.8"
 
+   python:
+     install:
+       - requirements: docs/requirements.txt
+
 The purpose of each key is:
 
 ``version``
@@ -345,9 +342,12 @@ The purpose of each key is:
 ``build.tools.python``
   Declares the Python version to be used.
 
+``python.install.requirements``
+  Specifies the Python dependencies to install required to build the documentation.
+
 After you commit these changes, go back to your project home,
 navigate to the "Builds" page, and open the new build that just started.
-You will notice that one of the lines contains ``python3.8``:
+You will notice that one of the lines contains ``python -mvirtualenv``:
 if you click on it, you will see the full output of the corresponding command,
 stating that it used Python 3.8.6 to create the virtual environment.
 
@@ -387,15 +387,19 @@ click on the |:pencil2:| icon, and add these contents:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
-   :emphasize-lines: 8-9
+   :emphasize-lines: 12-13
 
    version: 2
 
    build:
-     os: "ubuntu-20.04"
+     os: "ubuntu-22.04"
      tools:
        python: "3.8"
 
+   python:
+     install:
+       - requirements: docs/requirements.txt
+
    sphinx:
      fail_on_warning: true
 
@@ -414,11 +418,12 @@ go back to editing ``.readthedocs.yaml`` on GitHub and modify it as follows:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
-   :emphasize-lines: 2-4
+   :emphasize-lines: 4-6
 
    python:
-     # Install our python package before building the docs
      install:
+       - requirements: docs/requirements.txt
+       # Install our python package before building the docs
        - method: pip
          path: .
 
@@ -547,36 +552,40 @@ and a new build will be triggered for it.
    You can read more about :ref:`hidden versions <versions:hidden>`
    in our documentation.
 
-Show a warning for old versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. "Show a warning for old versions" feature is not available anymore.
+   We should re-write this section once we have the notification addons rolled out.
 
-When your project matures, the number of versions might increase.
-Sometimes you will want to warn your readers
-when they are browsing an old or outdated version of your documentation.
 
-To showcase how to do that, let's create a ``2.0`` version of the code:
-navigate to your GitHub repository, click on the branch selector,
-type ``2.0.x``, and click on "Create branch: 2.0.x from 'main'".
-This will trigger two things:
+   Show a warning for old versions
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Since ``2.0.x`` is your newest branch, ``stable`` will switch to tracking it.
-- A new ``2.0.x`` version will be created on your Read the Docs project.
-- Since you already have an active ``stable`` version, ``2.0.x`` will be activated.
+   When your project matures, the number of versions might increase.
+   Sometimes you will want to warn your readers
+   when they are browsing an old or outdated version of your documentation.
 
-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 :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.
+   To showcase how to do that, let's create a ``2.0`` version of the code:
+   navigate to your GitHub repository, click on the branch selector,
+   type ``2.0.x``, and click on "Create branch: 2.0.x from 'main'".
+   This will trigger two things:
 
-If you now browse the ``1.0.x`` documentation, you will see a warning on top
-encouraging you to browse the latest version instead. Neat!
+   - Since ``2.0.x`` is your newest branch, ``stable`` will switch to tracking it.
+   - A new ``2.0.x`` version will be created on your Read the Docs project.
+   - Since you already have an active ``stable`` version, ``2.0.x`` will be activated.
 
-.. figure:: /_static/images/tutorial/old-version-warning.png
-   :width: 80%
-   :align: center
-   :alt: Warning for old versions
+   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 :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
+   encouraging you to browse the latest version instead. Neat!
+
+   .. figure:: /_static/images/tutorial/old-version-warning.png
+      :width: 80%
+      :align: center
+      :alt: Warning for old versions
 
-   Warning for old versions
+      Warning for old versions
 
 Getting insights from your projects
 -----------------------------------