nbsphinx incompatibility with the pytorch_sphinx_theme

[calebrob6]

When including nbsphinx with pytorch_sphinx_theme several components of the theme break:

• Permalinks to sections are hidden
• The right (mobile) sidebar navigation expand/collapse buttons are hidden / don't work
• The right (mobile) sidebar navigation doesn't scroll with the page and instead is stuck on the top of the page

To see this in action compare the torchvision docs with our torchgeo docs.

If you clone https://github.com/microsoft/torchgeo and build the docs with and without nbsphinx listed as an extension in docs/conf.py you can also see these differences.

Any ideas what could be going on here?

@adamjstewart

[mgeier]

There are errors in the JavaScript console.

It probably has something to do with require.js?

You can try disabling it with https://nbsphinx.readthedocs.io/en/0.8.7/usage.html#nbsphinx_requirejs_path, but this might break widgets (https://nbsphinx.readthedocs.io/en/0.8.7/usage.html#nbsphinx_widgets_path).

[mgeier]

BTW, if you want to improve the support for the pytorch theme, you can have a look at https://nbsphinx.readthedocs.io/en/pytorch-theme/, which shows quite a few shortcomings.

I won't be actively working on this, but I'm happy to help where I can.

[mgeier]

There might be a problem with bootstrap version 4: #327.

This also sounds related: #519.

There have been similar problems with KaTeX, but those have been solved: #409, #412.

Here's some older discussion for context: #84, #128.

As you can see, dealing with require.js has been quite troublesome ...

[calebrob6]

Haha yep disabling require.js fixes everything I mentioned above. I think we're OK on widgets for now so will probably just use this until it becomes a problem.

It looks like the pytorch theme is using bootstrap 4 so I'm guessing that's what is going on in this case -- https://github.com/pytorch/pytorch_sphinx_theme/blob/master/pytorch_sphinx_theme/static/js/vendor/bootstrap.min.js

Thanks a bunch for the help!

[mgeier]

The pydata-sphinx-theme project seems to have found a solution for their very similar problem: pydata/pydata-sphinx-theme#167.

Would a similar thing be possible with the pytorch theme?

I'll re-open this issue, I hope it can be fixed without breaking widgets support.

[calebrob6]

I have no idea (web development is mostly voodoo to me 😄), but I'll open a similar issue with them with all this extra context.

Thanks again!