readthedocs.org: Broken sidebar when using YAML config, conda, and pip_install

Project URL: https://qnet.readthedocs.io/en/latest/index.html#
Build URL (if applicable): https://readthedocs.org/projects/qnet/builds/7008115/

I’m seeing a strange effect where the navigation sidebar is broken depending on the RTD configuration. The effect is that clicking on the “Read the Docs”/version at the very bottom of the sidebar does nothing (it should pop up the version selector). Also, on a small screen where the sidebar is hidden by default, clicking on the sidebar button (the symbol of three horizontal bars in the top left corner) has no effect (as opposed to showing the sidebar).

The broken behavior can be seen in the current build on the Project URL. When loading that page e.g. in Safari with an open Web Inspector, there is an error message that hints at the problem:

[Error] TypeError: undefined is not an object (evaluating 'SphinxRtdTheme.Navigation.enableSticky')
	(anonymous function) (index.html:365)
	f (jquery-2.0.3.min.js:3:2256)
	fireWith (jquery-2.0.3.min.js:3:3059)
	ready (jquery-2.0.3.min.js:1:12573)
	ge (jquery-2.0.3.min.js:1:10197)

The project uses a readthedocs.yml file and it’s set up to use conda, and also to install the package for which the documentation is generated via pip (pip_install: true)

It turns out that this is the problem. If I switch from pip_install to setup_py_install (and adapt the environment.yml file accordingly to install all pip-prerequisites manually), it works fine.

The commit that makes everything work is https://github.com/mabuchilab/QNET/commit/cc55fe4d789c32ee25436af4749a2d7d9bc6c2ad

I’ve reverted that commit to have a “broken” build, which I’ll leave up for a few days to give people a chance to look at it.

I wonder if the problem is that I have sphinx_rtd_theme listed in setup.py: maybe this overwrites the system-sphinx-rtd_theme during the pip_install of the package, which doesn’t happen with setup_py_install?

About this issue

Original URL
State: closed
Created 6 years ago
Comments: 41 (14 by maintainers)

Commits related to this issue

List separate rtd packages in setup.py This might possibly get around https://github.com/rtfd/readthedocs.org/issues/3925 — committed to mabuchilab/QNET by goerz 6 years ago
Switch RTD to setup_py_install pip_install on RTD is very buggy. See https://github.com/rtfd/readthedocs.org/issues/3925 https://github.com/rtfd/readthedocs.org/issues/3025 — committed to goerz/cookiecutter-pypackage by goerz 6 years ago
Fix RTD docs This addresses https://github.com/rtfd/readthedocs.org/issues/3925 — committed to mabuchilab/QNET by goerz 6 years ago
setup.py: there's currently an issue with RTDs sidebar when using sphinx-rtd-theme == 0.3.0 (see https://github.com/rtfd/readthedocs.org/issues/3925) — committed to BaPSF/bapsflib by rocco8773 6 years ago
docs/requirements.py: there's currently an issue with RTDs sidebar when using sphinx-rtd-theme == 0.3.0 (see https://github.com/rtfd/readthedocs.org/issues/3925 and https://github.com/rtfd/readthedocs... — committed to BaPSF/bapsflib by rocco8773 6 years ago

Most upvoted comments

Confirmed that this works again 😃 Thanks!

astrojuanlu on May 2, 2018

Believe this should be fixed with our latest deploy.

ericholscher on May 1, 2018

@kmuehlbauer, what’s the timeline for the next release? I have some documentation that I’m waiting to widely release until the search is fixed. (None of the suggested work-arounds in this thread worked for my case).

edited NVM, didn’t read far enough up the comment chain, thought you were one of the devs! Sorry about that.

SaOgaz on Apr 27, 2018

I know you are eager to get this fixed but I need to get some reviews of the proposed fix before it is merged. There are folks who will look at this but they are also busy. The more people looking at a particular fix or fixes on RTD in general, the better.

If you’ve never tested Read the Docs locally before, you would need to:

Go through the installation steps for a local instance
Check out the branch referenced in #3968 and build static files (run gulp)
Check out the proposed change to the theme (https://github.com/rtfd/sphinx_rtd_theme/pull/614) and point the local builder at that version using a local file:///

davidfischer on Apr 25, 2018

Boooo… Alright. I’ll try to get this resolved ASAP.

davidfischer on Apr 17, 2018

@jessetan Thanks for the explanation. I hope this can be solved somehow.

kmuehlbauer on Apr 15, 2018

This does not look like an issue in the theme itself. In the non-working branch http://debug-docs.readthedocs.io/en/conda_pip/ posted by @kmuehlbauer, the code that starts the theme code is SphinxRtdTheme.Navigation.enableSticky(), which is consistent with the 0.3.0 version of the theme. The actual theme code included is in readthedocs-doc-embed.js, which contains pre-0.3.0 theme code. My guess is that the RTD theme is packaged with other static JS assets into readthedocs-doc-embed.js, but that this has not been updated when the theme was set to version 0.3.0.

This would be fixed by updating the theme code in readthedocs-doc-embed.js, however that will break all sites that use an older version of the theme, since there is only one version of readthedocs-doc-embed.js. I don’t know enough about RTD internals to recommend any way (versioning scheme?) to make this work with all theme versions.

jessetan on Apr 15, 2018