Return stable version tag with stable version API/context data

[agjohnson]

I found myself wanting this information in our documentation portal. I'd rather display the tag that stable points to, rather than stable. There are a few places where we could display this information differently:

• On the docs flyout menu (so return this information from the footer API)
• Inside the sphinx config (so return this information alongside the context data)
• In the API directly

I don't believe we are currently tracking this, we're just tracking the changeset of the tag.

Alternatively, we could potentially make version rules as an alternative feature to stable version. I'll discuss this in a separate ticket.

[agjohnson]

See #4001 for discussion on automated rules for versioning.

[humitos]

This is related to #4529 that talks about showing the tag that stable points to in below the project's title.

[stsewd]

Here is my comment, we can change this in the theme and in the API response. We have the information available.

#4529 (comment)

[Jackenmen]

It seems that this information is available through API v3 under stable's aliases key but the problem is that this API requires authentication and I don't think there is any way to actually use it from a build. The deprecated API v2 tat doesn't require auth does not provide the same information. So basically I thought I have found a workaround but it doesn't actually work because I can't auth 😄

I wanted to get the information about the stable tag so that I can show the old version warning. I don't want to use the new Addons for it (I like the old warning formatting in sphinx-rtd-theme style to be nicer) but it seems that I lack the necessary metadata to do so.

[humitos]

but the problem is that this API requires authentication and I don't think there is any way to actually use it from a build.

We are having some conversations about removing the auth requirement from APIv3, but we haven't made the changes yet. Eventually, that would be the way to get this data at build time.

I wanted to get the information about the stable tag so that I can show the old version warning. I don't want to use the new Addons for it (I like the old warning formatting in sphinx-rtd-theme style to be nicer) but it seems that I lack the necessary metadata to do so.

You can use the JavaScript event readthedocs-addons-data-ready which is the new way to make custom integrations like this one. You can see an example of how our theme integrates the flyout as example using this data at readthedocs/sphinx_rtd_theme#1526

We plan to document this JavaScript event soon, so people can start building their own integrations. In the meanwhile, please open a new issue if you feel you need some help with it and we can talk over there.