Docs: update tutorial with the latest required changes

- `.readthedocs.yaml` config file is now required
- `sphinx-rtd-theme` is a required dependency and has to be installed via
  `python.install.requirements`
- remove invalid options from "Import Project" page
- comment out section about "Show warning banner"

Related #10626 (comment)

Author: humitos

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.
 
@@ -53,6 +57,7 @@ and it contains the following files:
   including the Sphinx configuration ``docs/source/conf.py``
   and the root document ``docs/source/index.rst`` written in reStructuredText.
 
+.. TODO: update this image once we have pushed the ``readthedocs.yaml`` to the repository
 .. figure:: /_static/images/tutorial/github-template.png
    :width: 80%
    :align: center
@@ -147,15 +152,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:|
 
@@ -319,19 +318,24 @@ In this section, we will show you some examples of what a configuration file sho
 Upgrading 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:
+For example, to explicitly use Python 3.11 to build 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: "3.11"
+
+   python:
+     install:
+       - requirements: docs/requirements.txt
 
 The purpose of each key is:
 
@@ -345,18 +349,22 @@ 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.
 
-.. figure:: /_static/images/tutorial/build-python3.8.png
+.. TODO: update this image with Python 3.11
+.. figure:: /_static/images/tutorial/build-python3.11.png
    :width: 80%
    :align: center
-   :alt: Read the Docs build using Python 3.8
+   :alt: Read the Docs build using Python 3.11
 
-   Read the Docs build using Python 3.8
+   Read the Docs build using Python 3.11
 
 Making warnings more visible
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -387,14 +395,18 @@ 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: "3.11"
+
+   python:
+     install:
+       - requirements: docs/requirements.txt
 
    sphinx:
      fail_on_warning: true
@@ -414,11 +426,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-7
 
    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 +560,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
 -----------------------------------