Skip to content

Commit 2f90839

Browse files
committed
Post: remove support for Sphinx 1.x
Small changelog blog post to communicate we are deprecating installing Sphinx 1.x automatically for projects created before Oct 20, 2020. Besides, the blog post briefly describes how to create a `requirements.txt` file and how to update the `.readthedocs.yaml` to install them. This is aligned with the deprecation of building without a config file. We are using the same timeline for both. The code removal of this feature flag is done at readthedocs/readthedocs.org#10365
1 parent 79d72cc commit 2f90839

File tree

1 file changed

+71
-0
lines changed

1 file changed

+71
-0
lines changed

remove-support-for-sphinx-1.x.rst

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
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

Comments
 (0)