Fix wrong version in title in Readthedocs documentation

[valeriupredoi]

Description

• Closes Version number in documentation title on readthedocs is wrong #3814
• Link to documentation: https://readthedocs.org/projects/esmvaltool/builds/26330015/

---

Before you get started

• ☝ Create an issue to discuss what you are going to do

Checklist

It is the responsibility of the author to make sure the pull request is ready to review. The icons indicate whether the item will be subject to the 🛠 Technical or 🧪 Scientific review.

• 🛠 This pull request has a descriptive title
• 🛠 Documentation is available
• 🛠 All checks below this pull request were successful

[bouweandela]

To see the version, you can run the command

curl -s https://esmvaltool--3815.org.readthedocs.build/en/3815/ | grep Welcome

For this branch, it shows 2.12.0.dev55+g198d16f9c.d20241119, so better than the current main which shows 0.1.0.dev50+gde43833.d20241114, but it still has the .d20241119 ending, meaning that the git repository had uncommitted changes (that readthedocs made) at the time where ESMValTool was installed.

[bouweandela]

Maybe see if we can copy the entire .readthedocs.yml from iris? e.g. I see they are installing differently: https://github.com/SciTools/iris/blob/2600fb9bd9a1309fa6e989c1728589aa8140fb94/.readthedocs.yml#L28-L31

[valeriupredoi]

I highly doubt that's the bit that fixes it, but yeah why not, I just plopped it in, let's see 🤞

[valeriupredoi]

curl -s https://esmvaltool--3815.org.readthedocs.build/en/3815/ | grep Welcome

ha love this, 'tis magic 😁

[valeriupredoi]

so I think I know what the cause is: at installation point, the pip install assigns a development version, see the raw output - much easier for me to read:

Successfully installed ESMValTool-2.12.0.dev56+gdf8d32339.d20241122

which is fine, that's the normal behaviour. But I think RTD import that version, moreover, git fetch --unshallow don't give a v2.11.0 at all - do you know why there's no 2.11?

[bouweandela]

This needs to be removed, you're installing twice now:

ESMValTool/.readthedocs.yaml

Lines 24 to 25 in df8d323

	post_create_environment:
	- conda run -n ${CONDA_DEFAULT_ENV} pip install . --no-deps

[valeriupredoi]

agh!

[bouweandela]

git fetch --unshallow don't give a v2.11.0 at all - do you know why there's no 2.11?

Because you're not building the v2.11.0 tag but this branch. The version you see on readthedocs should be the same as the one you see when running pip install --no-deps . locally. What --unshallow does is clone the full repository, including the tags, so setuptools-scm can figure out the proper version instead of 0.1.0.

The .d20241119 ending, meaning that the git repository had uncommitted changes (that readthedocs made) at the time where ESMValTool was installed, should not be there. From the raw build log, it looks like readthedocs modifies the environment.yml file. To avoid that the version ends with .d20241119, these changes need to be stashed prior to the installation of ESMValTool.

[valeriupredoi]

git fetch --unshallow don't give a v2.11.0 at all - do you know why there's no 2.11?

Because you're not building the v2.11.0 tag but this branch. The version you see on readthedocs should be the same as the one you see when running pip install --no-deps . locally. What --unshallow does is clone the full repository, including the tags, so setuptools-scm can figure out the proper version instead of 0.1.0.

The .d20241119 ending, meaning that the git repository had uncommitted changes (that readthedocs made) at the time where ESMValTool was installed, should not be there. From the raw build log, it looks like readthedocs modifies the environment.yml file. To avoid that the version ends with .d20241119, these changes need to be stashed prior to the installation of ESMValTool.

snap! That was the code change all along! But the flow runs a git stash after RTD cats the environment file, so why is it still picked up?

[bouweandela]

$ curl -s https://esmvaltool--3815.org.readthedocs.build/en/3815/ | grep Welcome | head -n 1
    <title>Welcome to ESMValTool’s documentation! &#8212; ESMValTool 2.12.0.dev57+gdeacbb304 documentation</title>

Looks perfect now!

[bouweandela]

That was the code change all along! But the flow runs a git stash after RTD cats the environment file, so why is it still picked up?

It runs the stash after the conda run pip install command but before the pip install command. Now that you've removed the conda run pip install one, it looks good.

[valeriupredoi]

ah so it was the double install that was messing things up - thanks a lot @bouweandela - just in time for Friday pub 🍺