diff --git a/docs/_static/images/tutorial/active-versions.png b/docs/_static/images/tutorial/active-versions.png new file mode 100644 index 00000000000..5aa5dc2563f Binary files /dev/null and b/docs/_static/images/tutorial/active-versions.png differ diff --git a/docs/_static/images/tutorial/build-python3.8.png b/docs/_static/images/tutorial/build-python3.8.png new file mode 100644 index 00000000000..20163a2c748 Binary files /dev/null and b/docs/_static/images/tutorial/build-python3.8.png differ diff --git a/docs/_static/images/tutorial/flyout-downloads.png b/docs/_static/images/tutorial/flyout-downloads.png new file mode 100644 index 00000000000..1e7e785e716 Binary files /dev/null and b/docs/_static/images/tutorial/flyout-downloads.png differ diff --git a/docs/_static/images/tutorial/inactive-versions.png b/docs/_static/images/tutorial/inactive-versions.png new file mode 100644 index 00000000000..ba205819ba4 Binary files /dev/null and b/docs/_static/images/tutorial/inactive-versions.png differ diff --git a/docs/_static/images/tutorial/old-version-warning.png b/docs/_static/images/tutorial/old-version-warning.png new file mode 100644 index 00000000000..0b1d14f1316 Binary files /dev/null and b/docs/_static/images/tutorial/old-version-warning.png differ diff --git a/docs/glossary.rst b/docs/glossary.rst index 28480f46b41..6590ac00219 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -7,6 +7,10 @@ Glossary `Main page `_ where you can see all your projects with their build status and import a new project. + flyout menu + Menu displayed on the documentation, readily accessible for readers, containing the list active versions, + links to the static downloads, and other useful information. + profile page Page where you can see the projects of a certain user. @@ -16,3 +20,8 @@ Glossary project page Another name for :term:`project home`. + + root URL + Home URL of your documentation without the ``/`` and ``/`` segments. + For projects without custom domains, the one ending in ``.readthedocs.io/`` + (for example, ``https://docs.readthedocs.io`` as opposed to ``https://docs.readthedocs.io/en/latest``). diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 73196d74f34..97ccee7f7ff 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -259,7 +259,10 @@ __ https://docs.github.com/en/github/managing-files-in-a-repository/managing-fi In the editor, add the following sentence to the file: - Lumache has its documentation hosted on Read the Docs. +.. code-block:: rst + :caption: docs/source/index.rst + + Lumache has its documentation hosted on Read the Docs. Write an appropriate commit message, and choose the "Create a **new branch** for this commit and start a pull request" option, @@ -282,6 +285,279 @@ 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! +Customizing the build process +----------------------------- + +The Settings page 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 `. +This has several advantages: + +- The configuration lives next to your code and documentation, tracked by version control. +- It can be different for every version (more on versioning in the next section). +- Some configurations are only available using the config file. + +Read the Docs works without this configuration by making some decisions on your behalf. +For example, what Python version to use, how to install the requirements, and others. + +.. tip:: + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + + python: + version: "3.8" + +The purpose of each key is: + +``version`` + Mandatory, specifies :doc:`version 2 of the configuration file `. + +``python.version`` + Declares the Python version to be used. + +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``: +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 + :width: 80% + :align: center + :alt: Read the Docs build using Python 3.8 + + Read the Docs build using Python 3.8 + +Making warnings more visible +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you navigate to your HTML documentation, +you will notice that the index page looks correct, +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, +which opens the build logs in plain text, +and you will see several warnings: + +.. code-block:: text + + WARNING: [autosummary] failed to import 'lumache': no module named lumache + ... + WARNING: autodoc: failed to import function 'get_random_ingredients' from module 'lumache'; the following exception was raised: + No module named 'lumache' + WARNING: autodoc: failed to import exception 'InvalidKindError' from module 'lumache'; the following exception was raised: + No module named 'lumache' + +To spot these warnings more easily and allow you to address them, +you can add the ``sphinx.fail_on_warning`` option to your Read the Docs configuration file. +For that, navigate to GitHub, locate the ``.readthedocs.yaml`` file you created earlier, +click on the |:pencil2:| icon, and add these contents: + +.. code-block:: yaml + :caption: .readthedocs.yaml + :emphasize-lines: 4-5 + + python: + version: "3.8" + + sphinx: + fail_on_warning: true + +At this point, if you navigate back to your "Builds" page, +you will see a ``Failed`` build, which is exactly the intended result: +the Sphinx project is not properly configured yet, +and instead of rendering an empty API page, now the build fails. + +The reason :py:mod:`sphinx:sphinx.ext.autosummary` and :py:mod:`sphinx:sphinx.ext.autodoc` +fail to import the code is because it is not installed. +Luckily, the ``.readthedocs.yaml`` also allows you to specify +which requirements to install. + +To install the library code of your project, +go back to editing ``.readthedocs.yaml`` on GitHub and modify it as follows: + +.. code-block:: yaml + :caption: .readthedocs.yaml + :emphasize-lines: 3-5 + + python: + version: "3.9" + # Install our python package before building the docs + install: + - method: pip + path: . + +With this change, Read the Docs will install the Python code +before starting the Sphinx build, which will finish seamlessly. +If you go now to the API page of your HTML documentation, +you will see the ``lumache`` summary! + +Enabling PDF and EPUB builds +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sphinx can build several other formats in addition to HTML, such as PDF and EPUB. +You might want to enable these formats for your project +so your users can read the documentation offline. + +To do so, add this extra content to your ``.readthedocs.yaml``: + +.. code-block:: yaml + :caption: .readthedocs.yaml + :emphasize-lines: 4-6 + + sphinx: + fail_on_warning: true + + formats: + - pdf + - epub + +After this change, PDF and EPUB downloads will be available +both from the "Downloads" section of the :term:`project home`, +as well as the :term:`flyout menu`. + +.. figure:: /_static/images/tutorial/flyout-downloads.png + :align: center + :alt: Downloads available from the flyout menu + + Downloads available from the flyout menu + +Versioning documentation +------------------------ + +Read the Docs allows you to have :doc:`several versions of your documentation `, +in the same way that you have several versions of your code. +By default, it creates a ``latest`` version +that points to the default branch of your version control system +(``main`` in the case of this tutorial), +and that's why the URLs of your HTML documentation contain the string ``/latest/``. + +Creating a new version +~~~~~~~~~~~~~~~~~~~~~~ + +Let's say you want to create a ``1.0`` version of your code, +with a corresponding ``1.0`` version of the documentation. +For that, first navigate to your GitHub repository, click on the branch selector, +type ``1.0.x``, and click on "Create branch: 1.0.x from 'main'" +(more information `on their documentation`__). + +__ 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, +and under "Active Versions" you will see two entries: + +- The ``latest`` version, pointing to the ``main`` branch. +- A new ``stable`` version, pointing to the ``origin/1.0.x`` branch. + +.. figure:: /_static/images/tutorial/active-versions.png + :width: 80% + :align: center + :alt: List of active versions of the project + + List of active versions of the project + +Right after you created your branch, +Read the Docs created a new special version called ``stable`` pointing to it, +and started building it. When the build finishes, +the ``stable`` version will be listed in the :term:`flyout menu` +and your readers will be able to choose it. + +.. note:: + + Read the Docs :ref:`follows some rules ` + to decide whether to create a ``stable`` version pointing to your new branch or tag. + To simplify, it will check if the name resembles a version number + like ``1.0``, ``2.0.3`` or ``4.x``. + +Now you might want to set ``stable`` as the *default version*, +rather than ``latest``, +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, +choose ``stable`` in the "Default version*" dropdown, +and hit :guilabel:`Save` at the bottom. +Done! + +Modifying versions +~~~~~~~~~~~~~~~~~~ + +Both ``latest`` and ``stable`` are now *active*, which means that +they are visible for users, and new builds can be triggered for them. +In addition to these, Read the Docs also created an *inactive* ``1.0.x`` +version, which will always point to the ``1.0.x`` branch of your repository. + +.. figure:: /_static/images/tutorial/inactive-versions.png + :width: 80% + :align: center + :alt: List of inactive versions of the project + + List of inactive versions of the project + +Let's activate the ``1.0.x`` version. +For that, go to the "Versions" on your :term:`project home`, +locate ``1.0.x`` under "Activate a version", +and click on the :guilabel:`Activate` button. +This will take you to a new page with two checkboxes, +"Active" and "Hidden". Check only "Active", +and click :guilabel:`Save`. + +After you do this, ``1.0.x`` will appear on the "Active Versions" section, +and a new build will be triggered for it. + +.. note:: + + You can read more about :ref:`hidden versions ` + in our documentation. + +Show a warning for old versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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: + +- 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. + +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, +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 + ---- That's the end of the tutorial, diff --git a/docs/versions.rst b/docs/versions.rst index 3c4ae86a931..3d61a8c4ca0 100644 --- a/docs/versions.rst +++ b/docs/versions.rst @@ -6,9 +6,8 @@ On initial import, we will create a ``latest`` version. This will point at the default branch for your VCS control: ``master``, ``default``, or ``trunk``. -We also create a ``stable`` version, -if your project has any tagged releases. -``stable`` will be automatically kept up to date to point at your highest version. +If your project has any tags or branches with a name following `semantic versioning `_, +we also create a ``stable`` version, tracking your most recent release. If you want a custom ``stable`` version, create either a tag or branch in your project with that name. @@ -24,7 +23,7 @@ If you develop on a branch that is different than the default for your VCS, you should set the **Default Branch** to that branch. You should push a **tag** for each version of your project. -These tags should be numbered in a way that is consistent with `semantic versioning `_. +These tags should be numbered in a way that is consistent with semantic versioning. This will map to your ``stable`` branch by default. .. note::