Doesn't work out-of-the-box on https://readthedocs.org/ when using the sphinx_rtd_theme (for projects created before October 20th 2020)
mgeier opened this issue · 7 comments
See readthedocs/sphinx_rtd_theme#238, should be fixed by readthedocs/sphinx_rtd_theme#897.
AFAIK, other themes are not affected.
I've just seen that there is a DONT_OVERWRITE_SPHINX_CONTEXT feature (https://read-the-docs.readthedocs.io/en/latest/guides/feature-flags.html), which would probably make it work.
It might have some unintended consequences, though.
readthedocs/sphinx_rtd_theme#897 has been merged, now we just have to wait for a new release (https://github.com/readthedocs/sphinx_rtd_theme/releases).
A new version of the RTD theme has been released in the meantime (hooray!), but RTD still seems to force sphinx-rtd-theme<0.5 by default ...
I've asked why the new version of the RTD theme is not enabled by default: readthedocs/readthedocs.org#7858
According to readthedocs/readthedocs.org#7858 (comment), the problem is solved for projects created after October 20th 2020, hooray!
Older projects will have to explicitly request a newer version.
One way seems to be to use the (undocumented) feature flag USE_SPHINX_LATEST (see https://docs.readthedocs.io/en/latest/guides/feature-flags.html).
Another way to get the new versions is to override the defaults by means of a requirements.txt file:
sphinx>=2
sphinx_rtd_theme>=0.5
I think other themes might be affected too, such as the PyData theme – I have not been able to make this work, neither locally nor on readthedocs (pybamm-team/PyBaMM#3089). @mgeier could you please help investigate this? Here is a link to the PR build and the build logs. I did bump up the Sphinx version to >= 6 in docs/requirements.txt (it was >=1.5 earlier).
However, I can see that other projects have been able to make this extension work with the same theme, maybe this is an issue with our configuration? It is almost similar to others' configurations – so I don't see any conflicts. Or, is it because they are newer projects unlike ours (i.e., post-October 2020) and we have to request the aforementioned feature flag(s) in this thread from readthedocs?
This issue is specifically about sphinx_rtd_theme, and I think there is nothing I can do except provide work-arounds (which are mentioned above).
If a similar thing also happens with other themes, this likely has different causes. Especially if it doesn't work locally either.
Please create a new issue.
Please provide a minimal reproducible example, otherwise it is unlikely that I can help.