Version number does not display properly on ReadTheDocs

[diazona]

In the documentation for our stable release 0.1, the version number at the top left is displayed as "setuptools-pyproject-migration 0.1.1.dev0+gfde5f75.d20231010". We need to fix that so it displays properly, e.g. for this release it should show 0.1, or for future releases something like 0.1.post0 or 0.1.1 or 0.2 or whatever.

[sjlongland]

Not sure if this is related or not… but git describe does not seem to see the release tags.

RC=0 stuartl@rikishi ~/projects/setuptools-pyproject-migration/work $ git describe
fatal: No annotated tags can describe 'fde5f75ee17445dc0ae03a9bbcd6713a1eaa4d1a'.
However, there were unannotated tags: try --tags.
RC=128 stuartl@rikishi ~/projects/setuptools-pyproject-migration/work $ git describe --tags
v0.1.0

[diazona]

Ooh good catch, yeah that does make sense. I don't remember offhand if setuptools-scm relies on git describe though, but it sounds plausible that it might.

If that's the case, then we might have to switch things around so that we manually create (annotated) tags, or at least create them in CI with a git command, rather than having Github create them for us as part of making a Github release. Honestly, that might not be a bad idea anyway, as it gives us more control over the tagging, but I think further investigation is needed before figuring out how to proceed.

[sjlongland]

I'm a bit surprised that Github doesn't create annotated tags actually.

[diazona]

Yeah same, or at least that it doesn't offer the option to do so.

[diazona]

I found a Stack Overflow question about this with some ideas to try.

The ReadTheDocs documentation does call out having to work around a dirty Git working tree, so that's one thing to try, but I'm not sure if that will be enough.

[sjlongland]

Yep, they also mention that RTD does sometimes manipulate files… https://stackoverflow.com/questions/35811267/readthedocs-and-setuptools-scm-version-wrong/41949974#41949974 in particular, suggests installing the module then reading out the version number directly.