Display actual version number (possibly a new feature request)

[orenbenkiki]

I posted this on stack overflow https://stackoverflow.com/questions/51840964/showing-the-version-number but got no answers.

TL;DR:

How do I make read-the-docs show the actual version number instead of the word "latest" or "stable" in the top-left of the documentation pages?

For the best of both worlds, it should say something like "latest v0.1.2".

Details:

I have a Python project, and I publish the documentation on read-the-docs. I'm using also using the sphinx_rtd_theme with no html_theme_options.

In my sphinx conf.py, I have:

...
import my_module
version = my_module.__version__
release = version
...

When I locally build the documentation, I see the version number displayed in the top-left, under the project name, as expected.

But when I look at the read-the-docs documentation, this version number is replaced with "latest".

It is great to know that the documentation is of the latest version! But it would be even better to know which version is documented.

It seems this is the expected default behavior. E.g. look at https://twine.readthedocs.io/en/latest/ - there are two versions available, latest and stable, but there's no (easy) way to tell what the actual version numbers are for either one.

It it matters: My version number is different for every commit. It is in a well-behaved x.y.z format, and is stored in an explicit version.py file. This file is part of the sdist package but is never checked in; instead it is generated by setup.py from the version control system. The latest tag is the x.y, and the distance-in-commits-from-tag-on-main-branch is the z.

[stsewd]

I'm attaching an image to be clear

We only set the version value when there isn't a conf.py file https://github.com/rtfd/readthedocs.org/blob/79032b53b0aa75bce4d4a522c7f4771db730aa6c/readthedocs/templates/sphinx/conf.py.conf#L18

But we always force to use the value from

https://github.com/rtfd/readthedocs.org/blob/79032b53b0aa75bce4d4a522c7f4771db730aa6c/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl#L80-L80

when the docs are on rtd

https://github.com/rtfd/sphinx_rtd_theme/blob/4fc72d97edf6ed177fce6720b95334b50111c275/sphinx_rtd_theme/layout.html#L108-L118

[humitos]

latest won't be associated to a version (or tag) in particular because it usually builds from master for git. So, I think that showing something like latest (x.y.z) doesn't make sense because in fact, the real x.y.z will be different than latest. If there is some value here, it could be the commit hash like latest (a1b2c3).

On the other hand, I think this could apply to stable since this version points to different versions from time to time. So, stable (x.y.z) does make sense to me.

[orenbenkiki]

I agree that it makes perfect sense to include the version number in stable.

As for latest, I agree that in general, the __version__ property of non-release commits is very suspect. However, in some projects (such as mine), the __version__ property is unique and does identify the specific commit - at least on the master branch, which is where the docs are built from.

Ideally there should be configurable option(s) for controlling the identifier associated to the stable and/or latest labels - be it nothing at all, the version number, the commit hash, both, or anything else that makes sense. This would allow each project to "do the right thing" to properly identify the documented version.

I agree that the reasonable default for such option(s) would be to include the version number in stable and the commit hash in latest. But I also think it would be useful to be able to override these defaults.

[stsewd]

We can use commit_name to get the actual name instead of latest or stable

https://github.com/rtfd/readthedocs.org/blob/6341bb155e2d5e55b19540e4b6be22ea33971853/readthedocs/builds/models.py#L150-L193

But, this would mean that we will lose the latest and stable tags from this part of the theme

https://github.com/rtfd/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/versions.html

Meanwhile, other themes will have the floating footer saying latest or stable, and the versions listed in this section will say latest/stable too (we could change the API to solve this)

Personally I kind of like the latest and stable tags, feels like uniform around all the docs. Also, just to clarify that you can see the commit in the end of the docs Revision 38894c5b

[humitos]

I'm not really sure that we want to change the default behavior here without making it configurable since it will affect to all our users suddenly.

For anyone interesting on using a custom current_version value we can enable the feature flag DONT_OVERWRITE_SPHINX_CONTEXT on that particular project.

Please, let us know.

If we agree on this, we can probably close the issue. @stsewd thoughts?

[orenbenkiki]

Yes, "all" I was asking for was some configuration option. I agree changing the default would be too disruptive.

That said, I don't fully understand the proposed solution. If I wanted to override the strings "stable" and "latest" to show additional information (wherever they appear on the web page, regardless of the chosen theme), what exactly should I write in my conf.py file?

E.g., would it be the case that if I just set current_version = "something", this something would be appended (as in "latest something", "stable something")? In which case I'd call it version_suffix rather than current_version. But perhaps I completely missed how the mechanism will work.

[corneliusroemer]

Is there any progress here? I opened an issue in some specific project (nextstrain/augur#817) only to later notice that there's this upstream issue, apparently still open.

For anyone coming here, SciTools/iris discussed different workarounds here: SciTools/iris#3992 and settled on this one: SciTools/iris#4030