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

[goerz]

• 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?

[goerz]

I can confirm that indeed the problem is that sphinx_rtd_theme is listed in setup.py. The commit https://github.com/mabuchilab/QNET/commit/df4b354255c3be2341bf0e18c01ae6238ba7673c also fixes the problem

[goerz]

I'm pretty sure this mess is caused in part by #3025

[kmuehlbauer]

@goerz I'm facing the same error. A bit confusing, though, because this behaviour was introduced sometimes after 28th of March.

You suggest to remove the sphinx_rtd_theme from the readthedocs.yml as a fix, right?

[goerz]

Yes (or rather, from the conda environment file that is referenced in readthedocs.yml).

More broadly, if you look at the details of the build process, you'll see that RTD installs the sphinx_rtd_theme automatically after setting up the environment (which is where the environments file is used), but before installing the package for which the documentation is being built. This is the line

conda install --yes --name latest mock pillow sphinx sphinx_rtd_theme

in https://readthedocs.org/projects/qnet/builds/7008115/

So I think what you want to do is to make sure nothing Sphinx-related is installed by anything in your readthedocs.yml. If you have pip_install: true, that would include the requirements listed in setup.py (setup_py_install: true ignores requirements). Does that make sense?

[kmuehlbauer]

Yes, I thought about that particular conda install line before. I think I need to experiment a bit, since my setup is slightly uncommon.

I install all package dependencies via the conda-part of RTD (sphinx, sphinx_rtd_theme, sphinxcontrib-bibtex and nbsphinx included).
But then I pull in some other artifacts inside conf.py, where I also do a pip install --no-deps of the package I want the API-doc created from. And I do a lot of mocking for the c-libs these package pulls in.

Here is a good build and bad build.

Anyway, I did not change anything in the configuration between these two runs. So something has changed either in rtd or in some other sphinx-related stuff.

OK, already long enough here. I'll begin removing sphinx_rtd_theme from the conda part of readthedocs.yml.

[mikaem]

I see this is as well here. Any more ideas on how to fix this? I have tried removing sphinx from my part of the conda installation, but I cannot seem to shake it no matter what. In open web inspector I'm getting the error message:
[Error] Failed to load resource: the server responded with a status of 404 (Not Found) (theme.css.map, line 0) from https://media.readthedocs.org/css/theme.css.map

[kmuehlbauer]

@mikaem @goerz

I did not manage to get around this. For debugging I set up a testing repo with master and conda_pip branch.

Whereas the master branch without readthedocs.yml works as expected. The simple approach with conda and a single (unneeded) dependency breaks.

• rtd project (https://readthedocs.org/projects/debug-docs/)
• working master (http://debug-docs.readthedocs.io/en/latest/)
• not working conda_pip branch (http://debug-docs.readthedocs.io/en/conda_pip/)

I really appreciate if this can be tracked down quite fast, since this breaks workflow, even on this simple example.

[mikaem]

@kmuehlbauer I've noticed that the build of @goerz that seems to work is using sphinx_rtd_theme version 0.2.4 and no conda-forge. With mine and your latest builds we are using sphinx_rtd_theme 0.3.0 and conda-forge. So it's just the latest version of the theme that seems to be problematic.

[kmuehlbauer]

@mikaem Thanks! I'll use defaults now. Hang on a bit.

[kmuehlbauer]

@mikaem This is a bit weird, while in the last build https://readthedocs.org/projects/debug-docs/builds/7041419/ I explicitely define defaults (and wiped the build before), the readthedocs conda-part uses conda-forge channel which pulls in sphinx_rtd_theme 0.3.0. Any ideas?

[kmuehlbauer]

It will be upgraded anyway (https://readthedocs.org/projects/debug-docs/builds/7041427/). :cry:

[kmuehlbauer]

Sorry for the ping @humitos. I was searching to find anything related to this problem here and found via a chain of issues and pr this. Interestingly the latest build of poliastro is facing the same problem (broken sidebar), but without using conda at all.

I'm currently a bit at loss, how to proceed from here.

[goerz]

@kmuehlbauer for https://readthedocs.org/projects/debug-docs/builds/7041419/, don't include sphinx_rtd_theme in readthedocs_environment.yml. I find that it works if there are no sphinx-related packages installed during any part of processing readthedocs.yml (which includes readthedocs_environment.yml)

[kmuehlbauer]

@goerz Thanks for looking into this. I did not inlcude sphinx_rtd_theme into this build. it is automatically installed by rtd themselves.

But as @mikaem already suggested, it might have to do with sphinx_rtd_theme version. In your case somehow v0.2.4 is used, while in his and mine v0.3.0 is pulled in. I'm almost convinced now that every new build with conda will break the sidebar, if v0.3.0 of the theme is used..

I therefore tried to get things running without conda. And this worked, because then sphinx_rtd_theme v0.2.4 is installed, see https://readthedocs.org/projects/debug-docs/builds/7041720/.

Something is terribly wrong.

[goerz]

I might be mistaken, but it looks to me like in that particular build you’re using the commit https://github.com/wradlib/debug-docs/commit/d2c5d8e1ac3a04251aa1e3075384a0a1955a920c which does have sphinx_rtd_theme listed in the requirements. So it gets installed twice, once from your readthedocs_environment.yml and then again in the line that RTD adds automatically to the build process to install the same package. That’s my whole point: that line that RTD adds is the only place where anything Sphinx-related should be installed.

[goerz]

Hmm... sorry, wrong commit. So never mind my last comment.

And yes, the problem is definitely the version of the sphinx_rtd_theme

[goerz]

I think they might have changed something on the RTD servers since I opened this issue: If you look at the older (working) build https://readthedocs.org/projects/qnet/builds/7008115/, you'll see that the line that RTD auto-inserts, i.e.

conda install --yes --name latest mock pillow sphinx sphinx_rtd_theme

installs version 0.2.4, whereas in your build is install 0.3.0 (which presumably is broken).

I've just retriggered a build for the same repo, and I'm still getting 0.2.4. Maybe it has something to do with build caches?

If indeed new (clean) builds automatically install 0.3.0, that would imply that RTD just broke all builds using conda.

I really wish RTD would limit themselves to provide a well-defined environment, and then simply execute the commands listed in readthedocs.yml, without adding their own stuff (basically, it should work like Travis handles testing; I should be able to tell RTD to just do make docs on my checked out repo)

[kmuehlbauer]

@goerz Yes, it seems sphinx_rtd_theme v0.3.0 breaks the sidebar.

See also this issue here: https://github.com/rtfd/readthedocs.org/issues/3829

Ping @jakirkham, do you experience broken sidebars in one of your projects rtd docs?

[jessetan]

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.

[Blendify]

@agjohnson can you take a look here?

[kmuehlbauer]

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

[davidfischer]

@jessetan is correct.

To get this working immediately, you should pin the RTD sphinx theme to sphinx_rtd_theme<0.3.0 (readthedocs.org does this by default but it can be overridden)

This is going to be a tricky one to resolve in a backwards compatible way. Here's my initial proposal:

• Modify the theme to always include the theme.js even if it is built by Read the Docs. The idea of the theme doing things differently based on whether it is running on RTD or not is an anti-pattern in my opinion. If RTD needs to override things, then that code should live in the readthedocs.org repository or in readthedocs-sphinx-ext and not in the theme.
• Modify readthedocs-doc-embed.js to only use the theme JavaScript if it isn't already loaded. This way readthedocs-doc-embed.js will still have the theme JS for old theme versions (<=0.3.0) but new versions won't rely on it.

[humitos]

To get this working immediately, you should pin the RTD sphinx theme to sphinx_rtd_theme<0.3.0 (readthedocs.org does this by default but it can be overridden)

Unfortunately, this workaround won't work if you are using Conda because of #3829 :(

[davidfischer]

Boooo... Alright. I'll try to get this resolved ASAP.

[davidfischer]

Here's the modification to the theme: https://github.com/rtfd/sphinx_rtd_theme/pull/614
Here's the modification to readthedocs-doc-embed.js: https://github.com/rtfd/readthedocs.org/pull/3968

[kmuehlbauer]

@davidfischer Any news on this? As time goes by more and more docs are breaking.

[davidfischer]

@kmuehlbauer, the proposed changes are awaiting review. Would you like to try them to see if they fix your issues?

[kmuehlbauer]

@davidfischer Sorry, but I do not have issues. And I have no idea how to test the behaviour on rtfd. The sidebar is broken on rtfd on all recent builds using sphinx_rtd_theme 0.3.0.

[davidfischer]

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:///

[kmuehlbauer]

@davidfischer Thanks for the pointers. I didn't know that rtd can be setup locally. Definitely worth a try.

[davidfischer]

Well, in the meantime, there is a workaround by using the setup_py_install: true option in our readthedocs.yml file (eg. https://github.com/mabuchilab/QNET/blob/ea06af5/readthedocs.yml#L10) which will use a pinned version (sphinx-rtd-theme<0.3).

[goerz]

@davidfischer Actually, I don't think there currently is any workaround, at least not when using conda. Current broken built where I tried pinning the theme: https://readthedocs.org/projects/qnet/builds/7100055/

At this point, I'm just waiting for your patches to make it into the next release, and onto the RTD servers. The docs are just going to be broken until then. It's not the end of the world. They're still mostly usable.

[kmuehlbauer]

@davidfischer I'm with @goerz, it's not the end of the world. Let's wait until this makes into the next release. But, as expected, the more projects get updated, the more reports about broken sidebar/search will find it's way here.

Anyway, great service! Keep up the good work.

[SaOgaz]

@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.

[ericholscher]

Believe this should be fixed with our latest deploy.

[astrojuanlu]

Confirmed that this works again :) Thanks!

[agjohnson]

I added rtfd/sphinx_rtd_theme#623, which addressed backwards incompatibility in the 0.3.0 release. 0.3.1 was released this morning and RTD was patched last night. You shouldn't have a problem building your projects with 0.3.0 and 0.3.1 now, and we have a more permanent fix coming soon.

Closing this for now, but reopen if you are still having trouble!

[SaOgaz]

I can't seem to get it to work for me, it looks like it's still grabbing v0.3.0 of the sphinx_rtd_theme, is that the problem? I tried clearing the build config a few times before restarting it. Currently trying to mess with forcing an update to 0.3.1 somehow in another branch.

build: https://readthedocs.org/projects/stak-notebooks/builds/7135343/

The following packages will be UPDATED:

    sphinx_rtd_theme: 0.1.9-py27_0  http://ssb.stsci.edu/astroconda --> 0.3.0-py27_0 conda-forge

[stsewd]

@SaOgaz the rtd sidebar works as expected on your project for me, what is the issue? About the old version, maybe something to do with the astroconda channel (sorry, if I wrong, I'm not familiar with conda)?

[SaOgaz]

What the what, it's working now. I wonder if my browser was pulling up a cached version somehow.... whoo, ignore my previous comments. Thanks rtd!

[humitos]

Since conda uses other channels, it takes some time to update when a new release is done