Post: remove support for Sphinx 1.x

[humitos]

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 https://github.com/readthedocs/readthedocs.org/pull/10365

📚 Rendered version 📚 : https://readthedocs-blog--220.org.readthedocs.build/change-sphinx-default-version/

[ericholscher]

For reviewing this, is the plan to do this at the same time at the config file deprecation? I thought in the call we talked about doing them at different times to simplify things, but not 100% sure.

Do we have a sense for how many projects this will effect? (Eg projects with the feature flag and not using requirements.txt)

[humitos]

For reviewing this, is the plan to do this at the same time at the config file deprecation? I thought in the call we talked about doing them at different times to simplify things, but not 100% sure.

I'm not sure about the timeframe. However, I want to treat them as two separate things. I feel telling people to do everything at once is asking them too much. I guess we are not rushing to change the Sphinx version installed by default, so we can do this after the configuration file. Besides, it's possible that we have less people hitting this issue after the configuration file migration, since some of them will do this extra step.

Do we have a sense for how many projects this will effect? (Eg projects with the feature flag and not using requirements.txt)

This is a hard question to answer with the data we have. It's possible, but it will require some thinking. We need,

• projects with the feature flag enabled (just those with Project.pub_date < Oct 20, 2020)
• projects without a configuration file OR projects with a configuration file but not using python.requirements OR using python.requirements but without specifying the sphinx version

If we narrow this question to "only projects that have had a build in the last year", we can say we have around ~1k projects building with Sphinx 1.x, https://ethicalads.metabaseapp.com/question/250-projects-using-sphinx-timeserie

Example for the week of April 24, 2023 (908 projects used Sphinx 1.8.6). It looks like a more manageable number:

[ericholscher]

@humitos Thanks for the data on that. It feels like a manageable set of users, and probably folks who aren't advanced users of the platform, but still actively using it.

I guess I'm still a bit confused on our timeline here. I think maybe we push this off until after the config file deprecation, just to keep things clean and simple, and not confuse people with multiple timelines and changes?

[humitos]

Yes. We can continue with this deprecation after the config file. I suppose we will have a little less people using Sphinx 1.8.x sheet that as well - some of them will follow our recommendation of pinning the dependencies.

[benjaoming]

I guess I'm still a bit confused on our timeline here. I think maybe we push this off until after the config file deprecation, just to keep things clean and simple, and not confuse people with multiple timelines and changes?

I was wondering something similar.

I think it would be great to deprecate this feature flag WITHOUT multiple timelines, i.e. include it with the other .readthedocs.yaml deprecations but we communicate it separately and exclusively to users affected.

Especially for this change, it should be very easy to detect the affected users and communicate directly with them?

1) Can we publish this on the blog in a way so it doesn't go in the newsletter? It would be valuable to reference. 2) Is it possible to use the text of this blog post for a direct email? Or maybe we just link the blog post, that should also be fine. 3) Can we create a notification message on readthedocs.org and readthedocs.com (similar to what we did with .readthedocs.yaml) with reference to the blog post?

[humitos]

I understood that we are not going to do this right now, but after the deprecation of the config file in October. We should come back to this on that date.

[humitos]

I simplified this post a lot and followed the same idea than in #232 and adapted with https://github.com/readthedocs/readthedocs.org/pull/10365#issuecomment-1658073001. We only have 24 projects with a build in the last 6 months using this version.