Open orenbenkiki opened 6 years ago
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
when the docs are on rtd
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.
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.
We can use commit_name
to get the actual name instead of latest or stable
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
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?
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.
Is there any progress here? I opened an issue in some specific project (https://github.com/nextstrain/augur/issues/817) only to later notice that there's this upstream issue, apparently still open.
For anyone coming here, SciTools/iris discussed different workarounds here: https://github.com/SciTools/iris/issues/3992 and settled on this one: https://github.com/SciTools/iris/pull/4030
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 nohtml_theme_options
.In my sphinx
conf.py
, I have: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
andstable
, 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 explicitversion.py
file. This file is part of thesdist
package but is never checked in; instead it is generated bysetup.py
from the version control system. The latest tag is thex.y
, and the distance-in-commits-from-tag-on-main-branch is thez
.