Feedback and version chooser missing

[amotl]

Problem

@matriv reported:

Hi! For the CrateDB ref docs, I don't see the drop down to select versions: https://cratedb.com/docs/crate/reference/en/latest/
(The arrow is there, but there are 0 options).

@msbt reported:

Guides and reference are the ones that aren't working properly.

@seut reported:

Also https://crate-jdbc.readthedocs.io/en/latest/ lost it’s version chooser. Old existing builds still has them. As old builds (they were build quite some time ago) work and only newer once which probably include a new version of the crate-docs-theme, this highly indicates that a recent crate-theme-version broke the version chooser.

Possible root cause

@msbt found this:

Related blogpost (which pretty much correlates with the day the problems began): https://about.readthedocs.com/blog/2024/07/addons-by-default/.

We are announcing the introduction of Read the Docs Addons to all the projects by default starting on October 7, 2024. Read the Docs Addons is the new modular implementation of all the features Read the Docs adds on top of your documentation: analytics, flyout menu, notifications and search, among others.

So, rolling back any release, as suggested, will probably not help, because the problem has been caused by an update at RTD.

Outlook

[...] try installing sphinx-build-compatibility extension in your project to mitigate them.

[amotl]

Root Cause

Indeed, it is about https://about.readthedocs.com/blog/2024/07/addons-by-default/.

Solution

That patch fixes most of the issues already.

• RTD: Add compatibility fixes for upstream changes at Read The Docs #535

Thanks for your excellent support, @msbt!

[amotl]

Backlog

404 on readthedocs-addons.js

@msbt said:

Maybe something changed on RTD, apparently it tries to load this file https://cratedb.com/_/static/javascript/readthedocs-addons.js which obviously is 404, actual file is localted here: https://cratedb.com/docs/crate/reference/_/static/javascript/readthedocs-addons.js

Resources from other extensions will get rendered like this in HTML:

_static/doctools.js
_static/copybutton.js
_static/design-elements.bbdccc18c4abea9397628f9fea3d48c2.js

Unfortunately, RTD injects an URL like this into the page:

/_/static/javascript/readthedocs-addons.js

This does not harmonize well with our custom domain setup.

Problem with item contents in version chooser ✅

• RTD: Add compatibility fixes for upstream changes at Read The Docs #535 (comment)

[amotl]

Version 0.35.0 has been released.

• https://pypi.org/project/crate-docs-theme/0.35.0/
• https://github.com/crate/crate-docs-theme/releases/tag/0.35.0

Changes for downstream projects.

• Chore: Update to crate-docs-theme 0.35.0 GA cratedb-guide#127
• Documentation: Update to crate-docs-theme 0.35.0 crate#16732

[amotl]

Works

Both feedback tools and version chooser are present.

• https://cratedb.com/docs/crate/reference/

Does not work

Feedback tools are present, but version chooser is missing.

• https://cratedb.com/docs/crate/crash/
• https://cratedb.com/docs/jdbc/

[amotl]

Those patches activate the version chooser also on the two projects missing it yet.

crate-jdbc

• Documentation: Fix Read The Docs configuration settings [2.7] crate-jdbc#424
• Documentation: Fix Read The Docs configuration settings [2.6] crate-jdbc#425
• Documentation: Fix Read The Docs configuration settings [2.5] crate-jdbc#426
• Documentation: Fix Read The Docs configuration settings [1.14] crate-jdbc#427
• Documentation: Update Read The Docs configuration settings [master] crate-jdbc#428

crash

• Documentation: Enable version chooser [master] crash#444
• Documentation: Enable version chooser [0.31] crash#445

[amotl]

We guess this has converged well, so let's close the ticket. Cheers, and thanks again @msbt.