Docs: mention that only semver versions are considered for the warning banner

[rhiaro]

We use a custom theme for the project on readthedocs. In Advanced Settings, the Show version warning setting is true. The docs say that a version warning banner for non-stable and non-latest versions will be inserted into a div with role="main". This was missing from the theme, so I added it, expecting the version warning to show up for this non-stable branch of the docs, but it hasn't. Is there something else I need to do to trigger the non-latest version warning?

• Read the Docs project URL: https://standard.openownership.org/en/rhiaro-theme-update/

[humitos]

Hi! I did a quick look on the page source you linked and I didn't find a div role="main" there. That's probably the problem.

[rhiaro]

Thanks for checking. It's definitely there though.

[humitos]

Is that the version where you want to show the warning?

From the screenshot it seems it's rhiaro-theme-update version, which is not in semver format. So, I'm not sure it can be compared with the other ones to decide whether or not to show the banner.

I do see the request to https://standard.openownership.org/_/api/v2/footer_html/?callback=callback&project=beneficial-ownership-data-standard&version=rhiaro-theme-update&page=index&theme=sphinxtheme&format=jsonp&docroot=%2Fdocs%2F&source_suffix=.rst and it returns the 0.2.0 version, which seems to be the latest. However, the field is_highest is true for the current version, so the warning is not added (see

readthedocs.org/readthedocs/core/static-src/core/js/doc-embed/version-compare.js

Lines 9 to 11 in b958bb8

	if (data.is_highest) {
	return;
	}

)

... and, if I understand correctly, as your version is not in semver format (as I guess in my first paragraph), we cannot compare it and we always mark it as is_highest=true. See

readthedocs.org/readthedocs/api/v2/views/footer_views.py

Lines 79 to 80 in b958bb8

	else:
	ret_val['is_highest'] = True

I checked that chunk of code in production:

In []: from readthedocs.projects.version_handling import parse_version_failsafe
In []: v = p.versions.get(slug='rhiaro-theme-update')
In []: parse_version_failsafe(v.verbose_name)
In []:

IMO, the documentation should be updated to reflect that it only works on versions with semver format names. cc @astrojuanlu

[rhiaro]

Thanks, that's helpful! I had understood from the documentation that anything that wasn't in semver would not be classed as stable and therefore have a warning added, which is the behaviour I'd like. I had a go at hunting down the code in the rtd repo but couldn't find it, so I appreciate those links.

[rhiaro]

Belated update - semver branch name solve the problem, thanks. I assume you're keeping this open for the docs update, but if not feel free to close.

[humitos]

We have deprecated the warning banner and it's currently only available for those projects that had it enabled already. We made this decision because all these confusions around when to show the banner and all the use cases involved here and each of them with their edge cases.

Lately, I've been thinking about "what's the best generic logic behind this problem?" that could cover most of the cases. I've reached to a simple implementation for the new addons we are working on on Read the Docs.

When a reader opens,

• the latest version: a notification to warn the user about some features may not yet be available is shown, suggesting them to read the stable version instead.
• a non-stable and not latest versions (e.g. v4.3 or v2.1rc2, etc): a notification to warn the user about reading a potential old/outdated version is shown and suggests to read stable version instead.

Would this logic works for your use case? I'd appreciate your feedback here 🙏🏼

In case you are curious, the PR that implements this logic is at readthedocs/addons#125.

[astrojuanlu]

I think this logic would work perfectly for us 💯

[jertel]

We have deprecated the warning banner and it's currently only available for those projects that had it enabled already. We made this decision because all these confusions around when to show the banner and all the use cases involved here and each of them with their edge cases.

Lately, I've been thinking about "what's the best generic logic behind this problem?" that could cover most of the cases. I've reached to a simple implementation for the new addons we are working on on Read the Docs.

When a reader opens,

• the latest version: a notification to warn the user about some features may not yet be available is shown, suggesting them to read the stable version instead.
• a non-stable and not latest versions (e.g. v4.3 or v2.1rc2, etc): a notification to warn the user about reading a potential old/outdated version is shown and suggests to read stable version instead.

Would this logic works for your use case? I'd appreciate your feedback here 🙏🏼

In case you are curious, the PR that implements this logic is at readthedocs/addons#125.

The RTD docs may need to be updated to reflect this. I was trying to figure out why I couldn't find a setting on the Advanced Settings screen, and eventually stumbled onto this closed issue, which fortunately led me to this comment.

This is how the docs currently read:

And the actual page is here: https://docs.readthedocs.io/en/stable/versions.html#version-warning

I can take a stab at a PR to add a mention that this is now deprecated and only visible to older projects if you'd like.

[humitos]

I can take a stab at a PR to add a mention that this is now deprecated and only visible to older projects if you'd like.

Sounds great to me! Thanks!

Once readthedocs/addons#174 gets merged and deployed, we will re-enable the non latest/stable version warning banner addon for all projects. Maybe the documentation could adds a note mentioning the new addons as well if you consider.

[humitos]

Once readthedocs/addons#174 gets merged and deployed, we will re-enable the non latest/stable version warning banner addon for all projects

This is done.