From 4a7304f54e3928f4d246a0cc09f3be2eacd26a3d Mon Sep 17 00:00:00 2001 From: Martin Yeo <40734014+trexfeathers@users.noreply.github.com> Date: Wed, 24 Aug 2022 17:27:33 +0100 Subject: [PATCH] Better handle `setuptools_scm` versioning (#4926) * Use setuptools_scm release-branch-semver version_scheme. * Properly handle all possible scm-rtd combinations. * What's new entry. * Use git stash to protect setuptools_scm from RTD. * Better version badges. * Better use of git stash. * Substitute commit SHAs in place of versions where appropriate. * Make rtd_version safe for use in shields.io badges. * Make rtd_version safe for use in shields.io badges. --- .readthedocs.yml | 6 ++++++ .../custom_sidebar_logo_version.html | 18 +++++++++++------ docs/src/conf.py | 20 ++++++++++++++++--- docs/src/whatsnew/3.3.rst | 3 +++ pyproject.toml | 1 + 5 files changed, 39 insertions(+), 9 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 58d5b26769..95f828a873 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -11,6 +11,12 @@ build: # to allow setuptools-scm to correctly auto-discover the version. - git fetch --unshallow - git fetch --all + # Need to stash the local changes that Read the Docs makes so that + # setuptools_scm can generate the correct Iris version. + pre_install: + - git stash + post_install: + - git stash pop conda: environment: requirements/ci/readthedocs.yml diff --git a/docs/src/_templates/custom_sidebar_logo_version.html b/docs/src/_templates/custom_sidebar_logo_version.html index 48bbe604a0..c9d9ac6e2e 100644 --- a/docs/src/_templates/custom_sidebar_logo_version.html +++ b/docs/src/_templates/custom_sidebar_logo_version.html @@ -1,20 +1,26 @@ {% if on_rtd %} {% if rtd_version == 'latest' %} - + {% elif rtd_version == 'stable' %} - + + + {% elif rtd_version_type == 'tag' %} + {# Covers builds for specific tags, including RC's. #} + + {% else %} - - + {# Anything else build by RTD will be the HEAD of an activated branch #} + + {% endif %} {%- else %} {# not on rtd #} - - + + {%- endif %} diff --git a/docs/src/conf.py b/docs/src/conf.py index 7f0c517e05..33864c4658 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -25,7 +25,9 @@ import os from pathlib import Path import re +from subprocess import run import sys +from urllib.parse import quote import warnings @@ -42,11 +44,21 @@ def autolog(message): # This is the rtd reference to the version, such as: latest, stable, v3.0.1 etc rtd_version = os.environ.get("READTHEDOCS_VERSION") +if rtd_version is not None: + # Make rtd_version safe for use in shields.io badges. + rtd_version = rtd_version.replace("_", "__") + rtd_version = rtd_version.replace("-", "--") + rtd_version = quote(rtd_version) + +# branch, tag, external (for pull request builds), or unknown. +rtd_version_type = os.environ.get("READTHEDOCS_VERSION_TYPE") # For local testing purposes we can force being on RTD and the version # on_rtd = True # useful for testing # rtd_version = "latest" # useful for testing # rtd_version = "stable" # useful for testing +# rtd_version_type = "tag" # useful for testing +# rtd_version = "my_branch" # useful for testing if on_rtd: autolog("Build running on READTHEDOCS server") @@ -85,10 +97,7 @@ def autolog(message): # The version info for the project you're documenting, acts as replacement for # |version|, also used in various other places throughout the built documents. - version = get_version("scitools-iris") -if version.endswith("+dirty"): - version = version[: -len("+dirty")] release = version autolog(f"Iris Version = {version}") autolog(f"Iris Release = {release}") @@ -303,6 +312,9 @@ def _dotv(version): "show_toc_level": 1, } +rev_parse = run(["git", "rev-parse", "--short", "HEAD"], capture_output=True) +commit_sha = rev_parse.stdout.decode().strip() + html_context = { # pydata_theme "github_repo": "iris", @@ -312,9 +324,11 @@ def _dotv(version): # custom "on_rtd": on_rtd, "rtd_version": rtd_version, + "rtd_version_type": rtd_version_type, "version": version, "copyright_years": copyright_years, "python_version": build_python_version, + "commit_sha": commit_sha, } # Add any paths that contain custom static files (such as style sheets) here, diff --git a/docs/src/whatsnew/3.3.rst b/docs/src/whatsnew/3.3.rst index 4459e92784..57478c9645 100644 --- a/docs/src/whatsnew/3.3.rst +++ b/docs/src/whatsnew/3.3.rst @@ -318,6 +318,9 @@ This document explains the changes made to Iris for this release #. `@rcomer`_ and `@wjbenfold`_ (reviewer) used ``pytest`` parametrization to streamline the gallery test code. (:pull:`4792`) +#. `@trexfeathers`_ improved settings to better working with + ``setuptools_scm``. (:pull:`4925`) + .. comment Whatsnew author names (@github name) in alphabetical order. Note that, diff --git a/pyproject.toml b/pyproject.toml index 5f3071bcc4..bdb8a431e5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,6 +11,7 @@ build-backend = "setuptools.build_meta" [tool.setuptools_scm] write_to = "lib/iris/_version.py" local_scheme = "dirty-tag" +version_scheme = "release-branch-semver" [tool.black] line-length = 79