|
| 1 | +.. post:: Jun 5, 2023 |
| 2 | + :tags: builders, deprecation |
| 3 | + :author: Manuel |
| 4 | + :location: BCN |
| 5 | + :category: Changelog |
| 6 | + |
| 7 | +Remove support for Sphinx 1.x |
| 8 | +============================= |
| 9 | + |
| 10 | +We are announcing the deprecation of building with Sphinx 1.x without specifying it in the project's dependencies (``requirements.txt``). |
| 11 | + |
| 12 | +Read the Docs **will stop installing Sphinx 1.x by default on projects created before October 20, 2020** |
| 13 | +that are not specifying a Sphinx version on their ``requirements.txt`` file. |
| 14 | +We plan to deploy these changes on **September 2023**. |
| 15 | + |
| 16 | +The main reason behind this decision is that users with old projects that create a new one are confused about the different Sphinx version installed. |
| 17 | +On new projects Read the Docs is installing the latest Sphinx version available, |
| 18 | +while on projects created before October 20, 2020 it's installing Sphinx 1.x. |
| 19 | +Besides, Sphinx 1.x has been unsupported for a long time now, |
| 20 | +and `we've experiencend some breaking changes when there are new releases of its dependencies <https://github.com/readthedocs/readthedocs.org/issues/9037>`_. |
| 21 | + |
| 22 | + |
| 23 | +Adding a ``requirements.txt`` |
| 24 | +----------------------------- |
| 25 | + |
| 26 | +If you have a project on Read the Docs that is not using a ``requirements.txt`` to pin the Sphinx version, |
| 27 | +**we strongly recommend you to create one as soon as possible** to avoid breaking builds once we deploy the changes. |
| 28 | + |
| 29 | +Here you have a minimal ``requirements.txt`` file that you can copy and paste to use in your project. |
| 30 | +With this config file your project should build successfully now |
| 31 | +and will keep working fine once we deploy the changes in September 2023. |
| 32 | + |
| 33 | +.. code:: |
| 34 | +
|
| 35 | + # docs/requirements.txt |
| 36 | + sphinx==6.2.1 |
| 37 | +
|
| 38 | +
|
| 39 | +Once you have created this file, |
| 40 | +you have to tell Read the Docs to install this depedencies. |
| 41 | +This is done using the ``python.install.requirements`` key in the ``.readthedocs.yaml`` configuration file |
| 42 | +as shown in the following example: |
| 43 | + |
| 44 | +.. code:: yaml |
| 45 | +
|
| 46 | + # ... your other configurations |
| 47 | +
|
| 48 | + python: |
| 49 | + install: |
| 50 | + - requirements: docs/requirements.txt |
| 51 | +
|
| 52 | +
|
| 53 | +.. note:: |
| 54 | + |
| 55 | + If you don't have a ``.readthedocs.yaml`` configuration file already in your repository, |
| 56 | + you should create one first. |
| 57 | + Read more about it in our |
| 58 | + `documentation <https://docs.readthedocs.io/en/stable/config-file/v2.html>`_ |
| 59 | + |
| 60 | + |
| 61 | +Once you added the ``requirements.txt`` file and the made the required changes in the ``.readtehdocs.yaml`` file, |
| 62 | +you are ready to trigger a new build and double-check that it worked as expected. |
| 63 | + |
| 64 | + |
| 65 | +Contact us |
| 66 | +---------- |
| 67 | + |
| 68 | +Get in touch with us `via our support`_ |
| 69 | +and let us know if you any trouble pining your Sphinx dependency. |
| 70 | + |
| 71 | +.. _via our support: https://readthedocs.org/support/ |
0 commit comments