[Website][Docs] index page shows wrong warning bar at top when 15.0 is selected

[mcrumiller]

When version 15.0 is selected, a warning at the top says that the selected version is 0.14.0, and prompts to switch.

https://arrow.apache.org/docs/index.html

Component(s)

Documentation

[AlenkaF]

Thanks for opening the issue! Don't know why this is happening. The versions file looks correct https://arrow.apache.org/docs/_static/versions.json.

One thing I am noticing is that the 15.0.0 version docs were built with PyData Sphinx Theme 0.14.0 and not 0.14.1. @raulcd I am looking at https://github.com/apache/arrow/tree/main/dev/release but am not sure where the package requirements are defined?

[mcrumiller]

Being wary of the decimal placement (15.0 versus 0.14.0) it looks like it's referencing version numbers for completely different packages.

[AlenkaF]

Yes, of the PyData Sphinx Theme package. It is a bug upstream fixed with 0.14.1 version. See #39658 (review)

[raulcd]

It seems the fix for the PyData sphinx package was not added to the 15.0.0 release. We probably should manually fix it on the published docs. The bug fix is tagged as 15.0.1 so I'll add it if we do a patch release.

[AlenkaF]

Not sure but I think the whole script tag here: https://github.com/apache/arrow-site/blob/asf-site/docs/index.html#L339 should be removed for all .html files of the version 15.0.0 in the asf-site/docs

[jorisvandenbossche]

I think the easiest short term fix is to repeat apache/arrow-site#431 (comment) (simple search/replace to set the version banner to false in the doc sources), like I did apache/arrow-site#426 for the 14.0.0 docs

[AlenkaF]

Cool thanks! Will do.

I am also looking at the 14.0.0 docs which should have a warning bar plus there is and issue in the version switcher. If 14.0.0 is selected the 15.0.0 is still displayed in the drop-down menu. I think we need to change the link to the versions.json here

arrow/docs/source/conf.py

Line 328 in c9ca62a

"json_url": "/docs/_static/versions.json",

to use full url, not relative path:

The JSON file needs to be at a stable, persistent, fully-resolved URL (i.e., not specified as a path relative to the sphinx root of the current doc build).

see https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html#configure-switcher-json-url

[jorisvandenbossche]

I am also looking at the 14.0.0 docs which should have a warning bar plus there

The reason it doesn't have the warning banner, is because we turned it off (with the same fix as I am suggesting above for 15.0.0). So indeed, once this is not the latest version anymore, we can do a similar patch to revert the banner change.

to use full url, not relative path:

It should be an "absolute" path, AFAIU, because it starts with a "/" (it's relative, but relative to the root of the site, i.e. arrow.apache.org, and so in practice it is absolute)

But, there seems to be something wrong with the theme_switcher_version_match. Also for the 14.0 docs, this is still set to "" (i.e. empty string)

[AlenkaF]

Yes, I am reverting DOCUMENTATION_OPTIONS.show_version_warning_banner to true for version 14.0.0 while changing DOCUMENTATION_OPTIONS.show_version_warning_banner to false for current 15.0.0.

Not sure how we can automate this for next release though.

As for the version switcher, I can also do a similar fix to change the DOCUMENTATION_OPTIONS.theme_switcher_version_match = ''; to DOCUMENTATION_OPTIONS.theme_switcher_version_match = '14.0/'; for the docs version 14.0.0.

[AlenkaF]

The proposed fix: apache/arrow-site#468

[AlenkaF]

The fix in the arrow-site is merged (apache/arrow-site#468) so this issue can be closed.

[jorisvandenbossche]

We still need to address the issue long term:

Not sure how we can automate this for next release though.

I am going to assume that the banner issue will be fixed upstream for the next release. But the "version_match" (being set to "" for the stable docs) is still a problem, because we just copy the stable docs to a version/ subdir. I assume that probably the easiest is that we update the release procedure for the doc building to include this search/replace to update DOCUMENTATION_OPTIONS.theme_switcher_version_match ?

[AlenkaF]

And I think the issue with DOCUMENTATION_OPTIONS.show_version_warning_banner will also in part be present with the next release, right? Even if we use new pydata sphinx theme version with the next release, we will have to change the DOCUMENTATION_OPTIONS.show_version_warning_banner for the stable docs when they get copied to a subfolder?

So yes, I would try with updating the post-08-docs.sh) to include changes for both

• DOCUMENTATION_OPTIONS.theme_switcher_version_match (from "" to "[version]") and
• DOCUMENTATION_OPTIONS.show_version_warning_banner (from false to true)

[jorisvandenbossche]

Ah, yes, show_version_warning_banner will also still have to be updated, but only once for the next release, and then afterwards (if we don't patch that anymore), it should be fine I think.