Table of contents with external URL no longer works in 0.10+

[djhoese]

The VisPy projects documentation is no longer building after upgrading to 0.10 of this theme. As far as I can tell the issue seems to be the external link to our Code of Conduct at the bottom of the index.rst page in our hidden TOC. You can find the file here:

https://raw.githubusercontent.com/vispy/vispy/main/doc/index.rst

but here is the snippet:

VisPy is a **high-performance interactive 2D/3D data visualization
library** leveraging the computational power of modern **Graphics
Processing Units (GPUs)** through the **OpenGL** library to display very
large datasets.

.. toctree::
  :caption: Getting VisPy
  :maxdepth: 1

  installation

.. toctree::
  :caption: Learning VisPy
  :maxdepth: 2

  getting_started/index

.. toctree::
  :caption: Additional Help
  :maxdepth: 2

  Documentation <overview>

.. toctree::
  :hidden:

  gallery/index
  API <api/modules>
  news
  Code of Conduct <https://github.com/vispy/vispy/blob/main/CODE_OF_CONDUCT.md>

The error I get:

Theme error:
An error happened in rendering the page api/modules.
Reason: KeyError('https://github.com/vispy/vispy/blob/main/CODE_OF_CONDUCT.md')
make: *** [Makefile:46: html_dev-pattern] Error 2

Note how it complains about rendering api/modules, but I'm pretty sure it is the Code of Conduct link in this file.

I was able to reproduce this error locally (normally we build in CI) just by updating from 0.9 to 0.10. FYI if anyone wants to try generating our docs themselves I suggest turning off sphinx-gallery:

cd doc
make html_dev-pattern PATTERN='asdfasdf'

[12rambau]

I think this is related to #911 I'll have a look shortly.

[pierre-haessig]

I don't know if it's the same issue, but I've reported an issue at sphinx-themes/sphinx-themes.org#105 (PyData theme demo at https://sphinx-themes.org/sample-sites/pydata-sphinx-theme/ fails to build). sphinx-themes maintainer told me to report it back to you.

The build error message looks a bit similar to VisPy's problem:

...
Theme error:
An error happened in rendering the page index.
Reason: KeyError('https://www.sphinx-doc.org')

[djhoese]

Yep, that looks pretty similar. And looking at the sphinx-themes.org index.rst we see the same type of TOC alias usage (or whatever you call that):

https://raw.githubusercontent.com/sphinx-themes/sphinx-themes.org/master/sample-docs/index.rst

[drammock]

Would it work to include the link to your CoC as an "external link" like so:

https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/header-links.html#navigation-bar-external-links

?

[djhoese]

My understanding is that the external link nature of my use case is not actually the problem, but the "alias" of the TOC entry:

API <api/modules>

Regardless, this is a feature that sphinx supports so it seems like something users should expect to work regardless of the theme.

[drammock]

My understanding is that the external link nature of my use case is not actually the problem, but the "alias" of the TOC entry

OK... earlier you said "I'm pretty sure it is the Code of Conduct link". Can you check a couple things for us?

1. when upgrading the theme from 0.9 to 0.10, did sphinx version also change? What is/are the sphinx version(s) you're testing with?
2. does it work under theme version 0.10 if you remove the CoC link?

[djhoese]

Yes, sorry. That was my original understanding based on the error message, but @12rambau bringing up the other issue made me think it was more general than just external URLs.

1. I'm 90% sure I only upgrade the theme and no longer have the terminal to check. Sphinx is at 5.1.1.
2. Yes it does build.

I just tried building with main now that #915 is merged but it looks like I get the same error. So maybe this is external link related.

Edit: Scratch the main building thing. Looks like it didn't install correctly in my environment. Let me try again...

[djhoese]

Closed by #915

Looks like this is no longer an issue with current main due to the fixes in #915. Looks like the new version did put some of the nav bar links in a "More" dropdown, but otherwise it looks good.

[drammock]

Great! FYI here's the docs on controlling the "more" dropdown:

https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/header-links.html#navigation-bar-dropdown-links

[djhoese]

Is there any plan for a 0.10.2 patch release or does the fix for this require a 0.11 release?