Language switcher doesn't work in Runtime docs and Nature docs

[kifumi]

The language switcher does not work in Runtime documents and Nature documents.

In the other docs, it works fine.

[woodsp-ibm]

If I look at ML, Opt or Finance I do not see it at all - its does work though!

Now it's there it seems, if I click in that area I get a dropdown and can change language - but statically the language and the dropdown arrow is not visible to me, as per the above image (Firefox/Windows if it matters)

[SooluThomas]

I think removing docs/_templates/versions.html file in PR #255 caused this. Though I'm not yet sure why things are working perfectly on Main Docs.

[Eric-Arellano]

Thanks for this report!

It should not be #255 - that is only on the main branch of qiskit_sphinx_theme and not the 1.11 branch.

It looks like this has been broken for some time. The missing content for Finance, ML, Opt, etc is because their files versionutils.py are setting version_label rather than language_label. We apparently changed in https://github.com/Qiskit/qiskit_sphinx_theme/pull/49/files#diff-93e646cab52c16e3a78d1b4e89128816440d65384cff09e35bdcb3ddcc428027R3 in October 2022 for the theme to expect language_label to describe the currently selected language. So, you can fix that problem with a diff like this:

diff --git a/docs/versionutils.py b/docs/versionutils.py
index 92033c4..3ad5248 100644
--- a/docs/versionutils.py
+++ b/docs/versionutils.py
@@ -46,7 +46,7 @@ def _extend_html_context(app, config):
     context["translations_list"] = translations_list
     context["current_translation"] = _get_current_translation(config) or config.language
     context["translation_url"] = partial(_get_translation_url, config)
-    context["version_label"] = _get_version_label(config)
+    context["language_label"] = _get_version_label(config)
 
 
 def _get_current_translation(config):

The reason that it's not clickable on Runtime and Nature is that jQuery is missing so the JavaScript code we have does not work. That is because Sphinx 5 used to include jQuery, but Sphinx 6 no longer does. The workaround is to install sphinxcontrib-jquery:

diff --git a/docs/conf.py b/docs/conf.py
index 0d1754b..eef7ee1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -99,6 +99,7 @@ extensions = [
     "sphinx.ext.doctest",
     "nbsphinx",
     "sphinx.ext.intersphinx",
+    "sphinxcontrib.jquery",
 ]
 html_static_path = ["_static"]
 templates_path = ["_templates"]
diff --git a/docs/versionutils.py b/docs/versionutils.py
index 29702e5..8305b5b 100644
--- a/docs/versionutils.py
+++ b/docs/versionutils.py
@@ -46,7 +46,7 @@ def _extend_html_context(app, config):
     context["translations_list"] = translations_list
     context["current_translation"] = _get_current_translation(config) or config.language
     context["translation_url"] = partial(_get_translation_url, config)
-    context["version_label"] = _get_version_label(config)
+    context["language_label"] = _get_version_label(config)
 
 
 def _get_current_translation(config):
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 5e96877..d5fb701 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -18,3 +18,4 @@ mypy-extensions>=0.4.3
 nbsphinx
 qiskit_sphinx_theme>=1.10
 networkx>=2.2,<2.6
+sphinxcontrib-jquery

I'm not sure why the other applications and Terra are working. They must be installing jQuery some other way. We should not be using jQuery anymore though: I opened #275 to track this and will release 1.11.1 to include jQuery with the Qiskit Sphinx Theme: #276.

--

Taking a step back, it is not sustainable for each repository to have its own versionutils.py. It is too easy to fall out of sync.

This should be provided for you by qiskit_sphinx_theme, IMO. At most, you only have to configure what languages you want.

I will submit soon PRs to each repo with the short-term fixes. But I also propose that the theme 1.12 starts including versionutils.py for you so that this Just Works in the future. (Along with other structural fixes for Ecosystem projects like #267)

[Eric-Arellano]

I've started to fix some ecosystem projects, like qiskit-community/qiskit-finance#256. The fix isn't complete though: when changing the language, we stop showing what is currently chosen.

I suspect this is because versionutils.py is not up-to-date. I will fix this soon.

[Eric-Arellano]

@SooluThomas figured out why the Finance docs weren't working when switching to other languages. We weren't properly deploying docs to qiskit.org/ecosystem, only the legacy qiskit.org/documentation. Fixed by qiskit-community/qiskit-translations#1108.

Everything is now fixed on the qiskit_sphinx_theme side thanks to #278. I am going through each project in the ecosystem today to fix any translations not working correctly.

The theme release for 1.12 will start including the versionutils.py logic in the theme itself so that we can stop copying and pasting it in every project: #262.

[Eric-Arellano]

The theme release for 1.12 will start including the versionutils.py logic in the theme itself so that we can stop copying and pasting it in every project: #262.

See #302