Readthedocs version tag

[jo-basevi]

As brought up in #494, the readthedocs versions are 1.1.5+0.g78f67ff.dirty for 1.1.5. I think the reason why is due to new files during added during readthedocs build (docs/source/_build/ and _readthedocs/), and auto-generated content is added to docs/source/conf.py. Due to these modifications in the repository, when payu is imported in docs/source/conf.py and the version is determined, versioneer marks the versions as dirty.

To prevent this, I've added an local pip install of payu to run before the docs build step, so the version is unaffected by the modified files. The documentation build for this PR now has no dirty tag: https://payu--505.org.readthedocs.build/en/505/.

With some local testing, if an 1.1.5 tag is checked out, there a modification to a file and then payu is locally installed, the version is 1.1.5+0.g78f67ff.dirty (payu --version). If there are no modifications, the version is 1.1.5.

[coveralls]

coverage: 55.953% (+0.2%) from 55.76%
when pulling c64ce4a on ACCESS-NRI:494-readthedocs-versions
into 2826621 on payu-org:master.

[jo-basevi]

Closes #494

[aidanheerdegen]

The preview build doesn't have dirty in the version string, but does have a "distance from commit" added to the version:

payu 1.1.5+4.gc64ce4a documentation

I suppose this is expected, because we're 4 commits since the last tag?

Will we only deploy to RTD on tagging?

[aidanheerdegen]

Changes seem reasonable, and worth trying to see if it fixes the issue.

[jo-basevi]

I suppose this is expected, because we're 4 commits since the last tag?

Yes, that is expected. With local testing of versioneer when at a tagged version and is install from an unchanged repository, the commit number and hash is left out.

Will we only deploy to RTD on tagging?

The latest version still points to latest development code (changes on the main branch) so this will reflect whats in payu/dev. What I have changed is https://payu.readthedocs.io/ to default to https://payu.readthedocs.io/en/stable/ where stable is the latest tagged version.

It is possible to configure latest to a branch - so it could be a release branch with the latest tag. I think stable might then point to the same documentation, and then I couldn't see an easy way to set up a development version to point to the latest changes in main..