Collapsable table of contents has changed

[georgemccabe]

Details

• Read the Docs project URL: https://readthedocs.org/projects/metplus/
• Build URL (correct result): https://readthedocs.org/projects/metplus/builds/18959565/
• Build URL (incorrect result): https://readthedocs.org/projects/metplus/builds/19085986/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/georgemccabe/

Within the last few weeks the table of contents on our documentation has stopped displaying correctly. We haven't made any changes to our docs that would explain this change. It looks like the versions of Python packages used in the builds have changed. From the build logs, I noticed the following differences:

Correct result used:

• sphinx-5.3.0
• sphinx-rtd-theme-1.1.1

New (incorrect result) used:

• sphinx-6.0.0
• sphinx-rtd-theme-0.5.1

Please let me know if you need any additional information from me. Thanks!

Expected Result

I expect the table of contents to include [+] icons to expand the 5.2, 5.5, 5.6, etc. sections seen in this build:
https://metplus.readthedocs.io/en/v5.0.0/Users_Guide/configuration.html

Actual Result

The [+] icons are no longer displayed:
https://metplus.readthedocs.io/en/bugfix_main_v5.0_no_changes/Users_Guide/configuration.html

[humitos]

It seems you are using an old version of the theme in the incorrect result. That's seems to be the problem.

Right now, you cannot use the combination sphinx==6.0.0 and sphinx-rtd-theme==1.1.1 because that theme version does not support Sphinx 6.x. I'd recommend you to give it a try at the pre-release sphinx-rtd-theme==1.2.0rc2 (https://pypi.org/project/sphinx-rtd-theme/1.2.0rc2/) that has support for Sphinx 6.x and give us any feedback you may have.

You can pin your dependencies using a requirements.txt file as described in this guide: https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#pinning-dependencies

[georgemccabe]

@humitos, thank you for the quick response. I was able to pin the versions of the packages to get the correct result. The docs generated using the release candidate version of sphinx-rtd-theme looks good as far as I can tell.

Our requirements file did not previously include sphinx or sphinx_rtd_theme. The mismatched versions of the packages were installed in the step before our requirements.txt files were read, which does not specify versions of the packages in the pip command. It sounds like the next sphinx-rtd-theme release is in progress, so this won't be an issue soon. Perhaps it would be good to use explicit versions for sphinx and sphinx_rtd_theme in that pip command to prevent these type of issues in the future?

Thank you again for your help!

[humitos]

I was able to pin the versions of the packages to get the correct result. The docs generated using the release candidate version of sphinx-rtd-theme looks good as far as I can tell.

I'm pretty happy to read this! 🎉 -- cc @benjaoming

Perhaps it would be good to use explicit versions for sphinx and sphinx_rtd_theme in that pip command to prevent these type of issues in the future?

There is a lot of legacy context about why we went from pinning these to not pinning these (... and I think that I don't even remember all of it at this point 😅 ). I don't think we will come back to pin them soon, tho 😄

In any case, as you mentioned, once 1.2.0 is released, it will be solved for all the users automatically due to pip's package resolution 💪🏼

[KellyStathis]

@humitos I also noticed some strange display issues which I was able to trace back to this same issue. Thanks to your recommendation, adding this to requirements.txt has fixed it:

sphinx==5.3.0
sphinx_rtd_theme==1.1.1

I also had not previously pinned a version of sphinx or sphinx_rtd_theme, so I was confused that an incompatible pair was used by default in the build.

I have two questions:

• Is there anything that could be done by Read the Docs so that users aren't experiencing unexpected display changes if they don't have these versions pinned?
• Would you recommend that we unpin these once 1.2.0 is released? Or should we move forward with pinning the most recent compatible versions of sphinx and sphinx_rtd_theme?

[benjaoming]

Hi @KellyStathis

These are really good questions! Sphinx 6 did make us have to do some extra work on the theme in order to avoid regressions.

We wrote a blog post that explains what's happening and how to use sphinx-rtd-theme 1.2.0rc2:

https://blog.readthedocs.com/sphinx6-upgrade/

Is there anything that could be done by Read the Docs so that users aren't experiencing unexpected display changes if they don't have these versions pinned?

Well, we had a medium priority of getting the theme released with compatibility for Sphinx 6 before it happened. It was a lot of Q&A'ing and not so much coding.

Would you recommend that we unpin these once 1.2.0 is released? Or should we move forward with pinning the most recent compatible versions of sphinx and sphinx_rtd_theme?

If you see only sphinx-rtd-theme in the landscape, then the explanation is this: The theme is supporting A LOT of Sphinx and docutils versions at the same time and it's difficult to Q&A new releases. This legacy is being reduced in upcoming releases.

However, it's important to note that most documentation projects use many other Sphinx extensions. When a new Sphinx release comes out, everything tends to be broken for a little while until new releases are sorted out.

It's best to pin.

Pinning doesn't mean to use == for everything, you can also say "get the latest Sphinx 6.0.x version or 6.x" and have much reduced risk of breakage. Sphinx itself has 2 major versions before deprecated APIs are removed, so if you have no extensions, you could write:

# This will get you the latest stable Sphinx 6.x
sphinx>=6,<7
# This will get you the latest sphinx-rtd-theme 1.2.x, starting from our current release candidate (rc2)
# Replace 1.2.0rc2 with just "1.2" after the final release
sphinx_rtd_theme>=1.2.0rc2,<1.3

Pinning is about reproducible builds and reducing the risk that documentation builds suddenly break in annoying and distracting and often counter-productive ways. There's a really good Read the Docs documentation article about it 😊

https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html