Problems about Sphinx-Version-Deadline "Oct 20, 2020"

[buhtz]

According to this section of the documentation older projects created before 20th October 2020 do use an old Sphinx (1.8.*) and newer projects do use the latest Sphinx.

Beside issues in the context of using Sphinx 1.8.* with modern Python versions I still reported via support email I see general problems and opportunities to improve the situation.

Verbosity

One problem I see from my point of view is that information is kind of hidden. My proposal is to make it very clear in the build process if a project uses a restricted/old Sphinx version: Add a colorful box in the web fronted, or a multi line ASCII-Art using echo command in the build script you use. And in the same place provide a link to further informations. Make it clear because no one expects something like this.

Give your users the rational

Explain somewhere why this deadline exists. I couldn't find a clear hint about it in your Changelog. Maybe #4250, #9036 is involved? Also in the Blog and Newsletter I couldn't find something related to that topic.

Process to change project status

In some of the Issues here I read a response that one of you maintainers would remove a project from that restriction. So it seems that it is somehow possible to give an "old" project the opportunity to build with the latest Sphinx. Make this process clear and announce it it to the users via the links I mentioned above.

So one Question here is how can I remove my "old" project from that build-with-old-sphinx-list?

[humitos]

According to this section of the documentation older projects created before 20th October 2020 do use an old Sphinx (1.8.*) and newer projects do use the latest Sphinx.

This refers only to "by default". That means that if the project doesn't pin the Sphinx version on their requirements.txt and Read the Docs will install 1.8.x or the latest by default.

Explain somewhere why this deadline exists. I couldn't find a clear hint about it in your Changelog

There is no extensive explanation about this. We just wanted projects to use a maintained version of Sphinx, but we didn't want to break old existing projects. Then on Oct 20, 2020; we deployed this change.

So one Question here is how can I remove my "old" project from that build-with-old-sphinx-list?

You need to create a requirements.txt file pinning the Sphinx version you want to install and use .readthedocs.yaml to install those requirements: https://docs.readthedocs.io/en/stable/config-file/v2.html#python

We are about to deprecate Sphinx 1.8.x soon (see #10365), so I don't think we will take any action here.

Let me know if there is anything else that's still unclear. Otherwise, I think I will close the issue.

[buhtz]

Dear humitos,

thanks for reaching out and replying my concerns.

According to this section of the documentation older projects created before 20th October 2020 do use an old Sphinx (1.8.*) and newer projects do use the latest Sphinx.

This refers only to "by default". That means that if the project doesn't pin the Sphinx version on their requirements.txt and Read the Docs will install 1.8.x or the latest by default.

Yes and that is how my project is configured: "by default". I don't pin the Sphinx version somehow and don't want to. I have no reason to do this. Using a requierements.txt is also not an option for my project. No matter if using such a txt file or a pyproject.toml it is not my goal to pin the Sphinx version in my upstream proejct. I want the default (latest).

There is no extensive explanation about this. We just wanted projects to use a maintained version of Sphinx, but we didn't want to break old existing projects. Then on Oct 20, 2020; we deployed this change.

I still don't get it. With deploying that change you "broke" my old project. So you got the opposite of what you wanted.

We are about to deprecate Sphinx 1.8.x soon (see #10365),

Can you name an unofficial date or timeframe?

I don't think we will take any action here.

As some of you offered in another Issue. Please just remove that flag from my two project.

https://readthedocs.org/projects/backintime/
https://readthedocs.org/projects/backintime-dev/

Let me know if there is anything else that's still unclear. Otherwise, I think I will close the issue.

I assume that maybe other projects no migrating to .readthedocs.yaml v2 do hitting that problem like I did. So I recommend to email all the "old" projects and inform them about that "feature-flag"/deadline. Just to prevent overloading your support channels. And offer them a way to remove that feature flag restriction without the need to pin a Sphinx version.

[humitos]

As some of you offered in another Issue. Please just remove that flag from my two project.

Done. Your projects should start installing Sphinx latest now by default.

I assume that maybe other projects no migrating to .readthedocs.yaml v2 do hitting that problem like I did.

All the projects are required to have a .readthedocs.yaml file starting on September 25, 2023. Read https://blog.readthedocs.com/migrate-configuration-v2/

So I recommend to email all the "old" projects and inform them about that "feature-flag"/deadline.

Yes, we will be communicating all the projects using Sphinx 1.8.x so they can pin their dependencies before we remove this feature flag.

[buhtz]

Awesome! I confirm it works now. Thanks for fixing this.