Use latest sphinx_rtd_theme by default?

[mgeier]

Currently, sphinx-rtd-theme<0.5 is used by default, see:

readthedocs.org/readthedocs/doc_builder/python_environments.py

Line 392 in dee00ce

negative='sphinx-rtd-theme<0.5',

What is blocking the use of the new RTD theme by default?

It looks like version 0.5.0 is already more than half a year old and there is even 0.5.1 available.

I'm aware that there are ways to use newer versions for individual projects, but I'm interested in the default case.

See also #7165, #7396.

[stsewd]

This is under a feature flag that defaults to use the latest version for projects created after October 20th 2020. This is done to avoid breaking docs from existing users that were using a default old sphinx version (1.8). I can enable it for your project if you want. But yeah, we recommend pinning your dependencies explicitly to avoid breaking the docs in the future and having reproducible builds.

[mgeier]

Thanks for the information, that's good to know!

This is under a feature flag that defaults to use the latest version for projects created after October 20th 2020. This is done to avoid breaking docs from existing users that were using a default old sphinx version (1.8).

OK, so does that mean that those "old" projects will never be upgraded to a higher Sphinx version if the default settings are used?

I guess this also means that it's not sufficient for those projects to request sphinx>=2, but they will in addition also have to request sphinx-rtd-theme>=0.5 (assuming they want the latest versions)?

I can enable it for your project if you want.

No, thanks, I don't use the RTD theme for most of my projects, and I changed the requirements.txt manually for where I need it:
spatialaudio/nbsphinx@rtd-theme^...rtd-theme
https://nbsphinx.readthedocs.io/en/rtd-theme/

The reason why I'm asking is that my Sphinx extension https://github.com/mgeier/sphinx-last-updated-by-git did not work by default on RTD and as it looks like it will keep not working by default for "old" projects. See also mgeier/sphinx-last-updated-by-git#1.

But yeah, we recommend pinning your dependencies explicitly to avoid breaking the docs in the future and having reproducible builds.

OK, good to know.

I think I personally prefer getting newer versions automatically, so I will probably rather use >= than == to request the Sphinx version.

[stsewd]

OK, so does that mean that those "old" projects will never be upgraded to a higher Sphinx version if the default settings are used?

For now, yeah. We plan to have a "supported versions" policy that may change that, but having users set the versions of their dependencies explicitly is more the goal we want to achieve.

I guess this also means that it's not sufficient for those projects to request sphinx>=2, but they will in addition also have to request sphinx-rtd-theme>=0.5 (assuming they want the latest versions)?

Yes, that's correct

[paulmueller]

This is done to avoid breaking docs from existing users that were using a default old sphinx version (1.8). I can enable it for your project if you want.

@stsewd But, to be thorough here, you would have to pin docutils==0.16.0 for those old projects as well, correct? Currently, all my projects are broken due to readthedocs/sphinx_rtd_theme#1115. Now I have to go through all my repositories and pin docutils (or sphinx and the rtd_theme). Wouldn't it be better to have an entry in the configuration file that allows you to set the version of rtd that you would like to use? Then rtd could just automatically install a pinned set of dependencies...

[paulmueller]

Just saw that there is already a PR: #8668