Wrong version in warning banner

[vnmabus]

The version compared and displayed in the warning banner is not the "version_match" attribute, but the theme version, as a result of #1394:

pydata-sphinx-theme/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

Line 432 in 4a29125

const version = DOCUMENTATION_OPTIONS.theme_version;

This result in the following image (note that the version of the banner is not the package version):

[12rambau]

It seems something went wrong with the fix: https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html
I made a release yesterday and the stable version is referenced as "unknown version" now

[drammock]

That is actually a different problem related to #1416. I noticed too but I'm teaching today so I can't look until Friday

[jklymak]

This seems to be an issue at https://pydata-sphinx-theme.readthedocs.io/en/stable/ as well?

[drammock]

This seems to be an issue at https://pydata-sphinx-theme.readthedocs.io/en/stable/ as well?

How so? The dropdown in the stable docs says "choose version" not "unknown version" nor an incorrect version string. "Choose version" is the new fallback value in case the version match cannot be determined; again, that is a different problem than the OP reported and is tracked in #1416

[jklymak]

https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html has a banner saying this is an unknown version and switch to stable, which lands you on the same page.

[drammock]

ah! my apologies, I was focused on the dropdown switcher and didn't even notice the banner. Nonetheless I believe that the cause is still the problem described in #1416 --- it's difficult to debug as I haven't been able to replicate it on PR builds or local builds.

[xia-stan]

I'm using Python 3.12, PyData Sphinx Theme 0.15.1, and Sphinx 7.2.6. I'm able to replicate this issue.

From what I can tell, the value unknown version is getting inserted because the generated file documentation_options.js has an empty string for VERSION:

const DOCUMENTATION_OPTIONS = {
    VERSION: '',
    LANGUAGE: 'en',
    COLLAPSE_INDEX: false,
    BUILDER: 'html',
    FILE_SUFFIX: '.html',
    LINK_SUFFIX: '.html',
    HAS_SOURCE: true,
    SOURCELINK_SUFFIX: '.txt',
    NAVIGATION_WITH_KEYS: false,
    SHOW_SEARCH_SUMMARY: true,
    ENABLE_SEARCH_SHORTCUTS: true,
};

Manually changing the VERSION to '1.0.0' and refreshing the page provides the expected message banner:

As to why VERSION was empty, I tracked this back to conf.py. I set the Sphinx variable version but not release. VERSION in documentation_options.js gets set to the release value and not version.

[drammock]

As to why VERSION was empty, I tracked this back to conf.py. I set the Sphinx variable version but not release. VERSION in documentation_options.js gets set to the release value and not version.

Thanks for the report @xia-stan. Indeed we use the release value and not the version value from conf.py. We are assuming folks follow what is stated in the Sphinx docs for release:

If you don’t need the separation provided between version and release, just set them both to the same value.

I think this issue can be closed now, on the assumption that if release is properly set, the warning banner will work as intented. But the fact that folks keep stumbling around the version switcher and the warning banner suggests that either (1) what we're doing is too fragile/magic, or (2) we're not documenting it clearly enough. I'll open a new issue to focus our attention on those improvements.