diff --git a/docs/user/_static/images/tutorial/github-template.png b/docs/user/_static/images/tutorial/github-template.png index 936e4ac13e5..e17f846dd6c 100644 Binary files a/docs/user/_static/images/tutorial/github-template.png and b/docs/user/_static/images/tutorial/github-template.png differ diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index 55af5deed97..0221159a1b7 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. @@ -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 `. -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 `. @@ -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 ` 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 -----------------------------------