diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 55af5deed97..18763761c01 100644 --- a/docs/user/tutorial/index.rst +++ b/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 ` 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 -----------------------------------