Skip to content

Version switcher config missing from some pages when using sphinx-tabs #2295

@krivard

Description

@krivard

Hi, I'm trying to configure the version switcher, but it's only behaving properly on some pages. When I deactivate the sphinx-tabs extension, all problems vanish. The reason I'm reporting it here instead of there is because I chased the problem to missing DOCUMENTATION_OPTIONS settings, which are controlled here. If it turns out that the pydata theme is trying to write DOCUMENTATION_OPTIONS to index but sphinx-tabs is somehow blocking or overwriting, then I'll go and yell over there :)

What I expected:

  • version switcher should populate on all pages for which it is configured in html_theme_options

What I found:

  • version switcher appears but does not populate on the index/home/root page
  • version switch does populate correctly on search results page, the generated index/sitemap, and a mystery subset of other pages in a more complex environment than the one I've included below. Oddly it doesn't seem to correspond to whether or not a sphinx-tabs tab appears on the page.
  • version switcher misbehavior exactly corresponds to whether or not the page includes DOCUMENTATION_OPTIONS settings in the built html

To reproduce:

  1. Set up a blank sphinx site with the following conf.py:
"""Configuration file for the Sphinx documentation builder."""
project = "version switcher bug"
extensions = [
    "sphinx_tabs.tabs",
]

html_theme = "pydata_sphinx_theme"

html_theme_options = {
    "switcher": {
        "json_url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json",
        "version_match": "dev"
    },
   "navbar_start": ["navbar-logo", "version-switcher"],
}
  1. Build the site and host locally by running python -m http.server --bind 127.0.0.1 8080 from the html directory
  2. Browse to http://127.0.0.1:8080/index.html
    • Observe: version switcher says "Choose version" and no versions are available in the dropdown
  3. Use the search bar to search any query and view the search results page
    • Observe: version switcher says "dev" and many version are available in the dropdown
  4. Confirm cause of misbehavior by running find [build_directory] -name "*.html" -exec grep DOCUMENTATION_OPTIONS {} +
    • Observe: DOCUMENTATION_OPTIONS is not set in index.html, only in search.html and genindex.html
  5. Remove the sphinx-tabs extension and rebuild the site
    • Observe: version switcher populates correctly on all pages and DOCUMENTATION_OPTIONS appears in index.html as it should.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions