readthedocs starts building with different theme without change to project configuration

[sigma67]

Details

• Read the Docs project URL: https://readthedocs.org/projects/ytmusicapi/
• Build URL (if applicable): https://readthedocs.org/projects/ytmusicapi/builds/21733027/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/{your_rtd_username}/

Expected Result

Continue building with latest sphinx as always

Actual Result

A few days ago I built a new release which now looks like this: https://ytmusicapi.readthedocs.io/en/1.2.1/

What it should actually look like: https://ytmusicapi.readthedocs.io/en/1.2.0/

it's reproducible, any time I run it with current project master: https://github.com/sigma67/ytmusicapi

as you can see, the .readthedocs.yaml was last changed a year ago and includes a reasonable configuration

I'm actually not sure if it's related to the sphinx version, but the theme looks very different and the Sphinx version seems very old to me.

[humitos]

We have been deprecating auto setting the RTD theme. I recommend you to pin your dependencies (see https://docs.readthedocs.io/en/stable/config-file/v2.html#requirements-file) and define "html_theme" Sphinx configuration to use the Read the Docs one.

[sigma67]

Is it necessary to pin dependencies? Shouldn't latest be the default?

To be clear I don't think setting the theme is the problem. It's already being set in conf.py if the dependency sphinx-rtd-theme is present. However it seems this is not the case any longer.

This is being called by the runner:

 python -m pip install --upgrade --no-cache-dir pillow mock==1.0.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.9.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<2.3 jinja2<3.1.0 

So it should be installed? However only passing a requirements.txt with sphinx>=6 and sphinx-rtd-theme seems to have fixed it for me.

Seems a bit of a step backward that I now have to configure something that wasn't needed before.

[humitos]

Is it necessary to pin dependencies?

No, but it's recommended to avoid surprises like installing different versions than the expected ones or depending on dependencies that are not installed. Read more about this at https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

Shouldn't latest be the default?

We are changing the default behavior because it was pretty confusing in the past. Starting on August 7th, new projects will always install the latest Sphinx version by default. Read more about this at https://blog.readthedocs.com/python-core-requirements-changed/

[humitos]

To be clear I don't think setting the theme is the problem. It's already being set in conf.py if the dependency sphinx-rtd-theme is present. However it seems this is not the case any longer.

If you want to use the Read the Docs Sphinx theme, you have to declare that in your conf.py as:

html_theme = 'sphinx_rtd_theme'

Previously, this was not required when building on Read the Docs, but we have changed that behavior recently. See #10638

[humitos]

I'm happy that you already found and solved the problem 👍🏼

We try to contact all the users when changing default behaviors like this one. If you haven't receive an email about this it's probably because our db query was wrong and excluded some valid users/projects and we don't have 100% accurate data to track this particular case.

[sigma67]

Thanks for the support!