ni-apis-python ReadTheDocs projects do not have a "stable" version

[bkeryan]

Bug Report

Normally, ReadTheDocs displays both a "latest" version corresponding to the main branch and a "stable" version corresponding to the most recent release tag. Showing the "stable" version by default and using it in hyperlinks avoids showing customers information about unreleased changes.

Because ni-apis-python is a monorepo, ReadTheDocs does not recognize any of its release tags, so it doesn't show a stable version.

See https://readthedocs-theme.readthedocs.io/en/latest/versions.html for more info.

Repro or Code Sample

Visit https://niprotobuftypes.readthedocs.io/en/stable/

Expected Behavior

It shows the documentation for the most recent release.

Current Behavior

It displays an HTTP 404 error.

Context

I am updating the InterSphinx mapping for https://measurement-plugin-python.readthedocs.io/en/stable/ and it errors out when I try to link to stable releases.

Your Environment

N/A

AB#3907496

[mjohanse-emr]

All the documentation I can find on "stable" builds says that it searches git tags for the most recent non-prerelease version (e.g. v1.0.0).

All of the git tags in ni-apis-python take the form of package_name/version which doesn't follow the PEP 440 semantic versioning regex. I think we would have to change our tag format from
ni.protobuf.types/1.2.0
to
ni.protobuf.types-1.2.0

However, there is one more complication that I don't quite understand. If ReadTheDocs always looks for the latest released git tag, won't it sometimes read the tag for the wrong package, if something was released more recently? Perhaps it's smart enough to determine which tags to look at based on the package name? Or possibly it only reads tags associated with the commits/PRs it builds against (are there even tags associated with commits/PRs?)?

[mjohanse-emr]

After some further research, it looks like we may need to consider automation rules to manage versions. Perhaps these can be defined in the readthedocs.yml file rather than set manually in the ReadTheDocs UI.

Then we can disable the default "Stable" logic.

Most of this info was from the google AI summary, so keep that in mind.

[bkeryan]

It looks like we can set up an automation rule to activate new versions that match the tag ^ni\.protobuf.types/.*$. However, I think RtD will display the full tag in the version selector, which is not ideal.

We can also set up an automation rule to set the version as default, and we can use regex to filter out .dev releases. I think that if we combine all of these, we will end up activating versions called ni.protobuf.types/1.2.1, ni.protobuf.types/1.3.0, etc. and setting the most recent one as the default version. This solves the problem of showing users the most recent stable release, but it doesn't solve the problem of letting other packages use Intersphinx to link to the most recent stable release because the most recent stable release doesn't have a fixed name like stable.

Another approach is to create a tag or branch called ni.protobuf.types/stable so that we can use Git to tell RtD which version is the stable version. I think that we could create an automation rule that updates a stable tag based on this. https://til.simonwillison.net/readthedocs/stable-docs goes into what else is involved.

I think readthedocs/readthedocs.org#11183 could potentially solve our problem. The redirect workaround described in that issue could also work, but I think we would need to update the redirect manually.