From 38d15bed86393d586f03f94ee7bb80b94643ff72 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Thu, 4 Feb 2021 22:29:01 +0000 Subject: [PATCH 1/5] automate docs discovery of iris and python versions --- docs/src/conf.py | 11 ++++++++--- docs/src/whatsnew/latest.rst | 4 ++-- docs/src/whatsnew/latest.rst.template | 4 ++-- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index 8be849b7ce..b1fc888aae 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -43,6 +43,7 @@ def autolog(message): for item, value in os.environ.items(): autolog("[READTHEDOCS] {} = {}".format(item, value)) + # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, @@ -92,12 +93,16 @@ def autolog(message): # -- General configuration --------------------------------------------------- -# Create a variable that can be insterted in the rst "|copyright_years|". -# You can add more vairables here if needed +# Create a variable that can be inserted in the rst "|copyright_years|". +# You can add more variables here if needed. rst_epilog = """ .. |copyright_years| replace:: {year_range} +.. |python_version| replace:: {python_version} +.. |iris_version| replace:: {iris_version} """.format( - year_range="2010 - {}".format(upper_copy_year) + year_range=f"2010 - {upper_copy_year}", + python_version=".".join([str(i) for i in sys.version_info[:3]]), + iris_version=f"v{version}", ) # Add any Sphinx extension module names here, as strings. They can be diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index dae4da4ba6..7b567c9f12 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -1,7 +1,7 @@ .. include:: ../common_links.inc - -************ +|iris_version| (unreleased) +*************************** This document explains the changes made to Iris for this release (:doc:`View all changes `.) diff --git a/docs/src/whatsnew/latest.rst.template b/docs/src/whatsnew/latest.rst.template index 0992a5c9bc..6676175908 100644 --- a/docs/src/whatsnew/latest.rst.template +++ b/docs/src/whatsnew/latest.rst.template @@ -1,7 +1,7 @@ .. include:: ../common_links.inc - -************ +|iris_version| (unreleased) +*************************** This document explains the changes made to Iris for this release (:doc:`View all changes `.) From 22a1facfdc5da1751fd9ab50d611ed2792b459ee Mon Sep 17 00:00:00 2001 From: Bill Little Date: Thu, 4 Feb 2021 23:29:11 +0000 Subject: [PATCH 2/5] update release docs + whatsnew entry --- docs/src/developers_guide/release.rst | 27 ++++++++++++++------------- docs/src/whatsnew/latest.rst | 7 +++++-- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/src/developers_guide/release.rst b/docs/src/developers_guide/release.rst index dd3f96b43d..8ca4948d47 100644 --- a/docs/src/developers_guide/release.rst +++ b/docs/src/developers_guide/release.rst @@ -121,7 +121,7 @@ release process is to be followed, including the merge back of changes into Maintainer Steps ---------------- -These steps assume a release for ``v1.9`` is to be created +These steps assume a release for ``v1.9`` is to be created. Release Steps ~~~~~~~~~~~~~ @@ -131,25 +131,26 @@ Release Steps release as it should already exist #. Update the what's new for the release: - * Copy ``docs/src/whatsnew/latest.rst`` to a file named - ``v1.9.rst`` - * Delete the ``docs/src/whatsnew/latest.rst`` file so it will not - cause an issue in the build + * Use git to rename ``docs/src/whatsnew/latest.rst`` to the release + version file ``v1.9.rst`` + * Use git to delete the ``docs/src/whatsnew/latest.rst.template`` file * In ``v1.9.rst`` update the page title (first line of the file) to show - the date and version in the format of ``v1.9 (DD MMM YYYY)``. For - example ``v1.9 (03 Aug 2020)`` + the release date in the format of ``v1.9 (DD MMM YYYY)``. For + example ``v1.9 (03 Aug 2020)``. Note that, the release version in the + title is updated automatically * Review the file for correctness - * Work with the development team to create a 'highlights' section at the - top of the file, providing extra detail on notable changes - * Add ``v1.9.rst`` to git and commit all changes, including removal of - ``latest.rst`` + * Work with the development team to populate the ``Release Highlights`` + dropdown at the top of the file, which provides extra detail on notable + changes + * Use git to add and commit all changes, including removal of + ``latest.rst.template`` #. Update the what's new index ``docs/src/whatsnew/index.rst`` - * Temporarily remove reference to ``latest.rst`` + * Remove the reference to ``latest.rst`` * Add a reference to ``v1.9.rst`` to the top of the list -#. Update the ``Iris.__init__.py`` version string, to ``1.9.0`` +#. Update the ``iris.__init__.py`` version string e.g., to ``1.9.0`` #. Check your changes by building the documentation and viewing the changes #. Once all the above steps are complete, the release is cut, using the :guilabel:`Draft a new release` button on the diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 7b567c9f12..25d626a57d 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -77,8 +77,11 @@ This document explains the changes made to Iris for this release (:pull:`3958`) #. `@bjlittle`_ clarified in the doc-string that :class:`~iris.coords.Coord` - is now an `abstract base class`_ of coordinates since Iris ``3.0.0``, and - it is **not** possible to create an instance of it. (:pull:`3971`) + is now an `abstract base class`_ since Iris ``3.0.0``, and it is **not** + possible to create an instance of it. (:pull:`3971`) + +#. `@bjlittle`_ added automated Iris version discovery for the ``latest.rst`` + in the ``whatsnew`` documentation. (:pull:`3981`) 💼 Internal From 3b2d33959cc77180535b65557d585c05a9b44e22 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Fri, 5 Feb 2021 10:30:13 +0000 Subject: [PATCH 3/5] add build_date --- docs/src/conf.py | 2 ++ docs/src/developers_guide/release.rst | 13 ++++++------- docs/src/whatsnew/latest.rst | 4 ++-- docs/src/whatsnew/latest.rst.template | 4 ++-- 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index b1fc888aae..8ccbcea74c 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -99,10 +99,12 @@ def autolog(message): .. |copyright_years| replace:: {year_range} .. |python_version| replace:: {python_version} .. |iris_version| replace:: {iris_version} +.. |build_date| replace:: {build_date} """.format( year_range=f"2010 - {upper_copy_year}", python_version=".".join([str(i) for i in sys.version_info[:3]]), iris_version=f"v{version}", + build_date=f"({datetime.datetime.now().strftime('%d %b %Y')})", ) # Add any Sphinx extension module names here, as strings. They can be diff --git a/docs/src/developers_guide/release.rst b/docs/src/developers_guide/release.rst index 8ca4948d47..70dee1fd4b 100644 --- a/docs/src/developers_guide/release.rst +++ b/docs/src/developers_guide/release.rst @@ -129,15 +129,15 @@ Release Steps #. Create the branch ``1.9.x`` on the main repo, not in a forked repo, for the release candidate or release. The only exception is for a point/bugfix release as it should already exist +#. Update the ``iris.__init__.py`` version string e.g., to ``1.9.0`` #. Update the what's new for the release: * Use git to rename ``docs/src/whatsnew/latest.rst`` to the release version file ``v1.9.rst`` * Use git to delete the ``docs/src/whatsnew/latest.rst.template`` file - * In ``v1.9.rst`` update the page title (first line of the file) to show - the release date in the format of ``v1.9 (DD MMM YYYY)``. For - example ``v1.9 (03 Aug 2020)``. Note that, the release version in the - title is updated automatically + * In ``v1.9.rst`` remove the ``[unreleased]`` caption from the page title. + Note that, the Iris version and release date are updated automatically + when the documentation is built * Review the file for correctness * Work with the development team to populate the ``Release Highlights`` dropdown at the top of the file, which provides extra detail on notable @@ -150,8 +150,7 @@ Release Steps * Remove the reference to ``latest.rst`` * Add a reference to ``v1.9.rst`` to the top of the list -#. Update the ``iris.__init__.py`` version string e.g., to ``1.9.0`` -#. Check your changes by building the documentation and viewing the changes +#. Check your changes by building the documentation and reviewing #. Once all the above steps are complete, the release is cut, using the :guilabel:`Draft a new release` button on the `Iris release page `_ @@ -171,7 +170,7 @@ Post Release Steps new headings #. Add back in the reference to ``latest.rst`` to the what's new index ``docs/src/whatsnew/index.rst`` -#. Update ``Iris.__init__.py`` version string to show as ``1.10.dev0`` +#. Update ``iris.__init__.py`` version string to show as ``1.10.dev0`` #. Merge back to master diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 25d626a57d..fbb98cb1e3 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -1,7 +1,7 @@ .. include:: ../common_links.inc -|iris_version| (unreleased) -*************************** +|iris_version| |build_date| [unreleased] +**************************************** This document explains the changes made to Iris for this release (:doc:`View all changes `.) diff --git a/docs/src/whatsnew/latest.rst.template b/docs/src/whatsnew/latest.rst.template index 6676175908..de02207474 100644 --- a/docs/src/whatsnew/latest.rst.template +++ b/docs/src/whatsnew/latest.rst.template @@ -1,7 +1,7 @@ .. include:: ../common_links.inc -|iris_version| (unreleased) -*************************** +|iris_version| |build_date| [unreleased] +**************************************** This document explains the changes made to Iris for this release (:doc:`View all changes `.) From cb28b9b84154194ded0acc2744e75277fd7726e6 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Fri, 5 Feb 2021 10:53:55 +0000 Subject: [PATCH 4/5] review actions --- docs/src/conf.py | 17 ++++++----------- docs/src/developers_guide/release.rst | 6 +++--- 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index 8ccbcea74c..f8941a80fc 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -95,17 +95,12 @@ def autolog(message): # Create a variable that can be inserted in the rst "|copyright_years|". # You can add more variables here if needed. -rst_epilog = """ -.. |copyright_years| replace:: {year_range} -.. |python_version| replace:: {python_version} -.. |iris_version| replace:: {iris_version} -.. |build_date| replace:: {build_date} -""".format( - year_range=f"2010 - {upper_copy_year}", - python_version=".".join([str(i) for i in sys.version_info[:3]]), - iris_version=f"v{version}", - build_date=f"({datetime.datetime.now().strftime('%d %b %Y')})", -) +rst_epilog = f""" +.. |copyright_years| replace:: {2010 - upper_copy_year} +.. |python_version| replace:: {'.'.join([str(i) for i in sys.version_info[:3]])} +.. |iris_version| replace:: v{version} +.. |build_date| replace:: ({datetime.datetime.now().strftime('%d %b %Y')}) +""" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom diff --git a/docs/src/developers_guide/release.rst b/docs/src/developers_guide/release.rst index 70dee1fd4b..56328f910f 100644 --- a/docs/src/developers_guide/release.rst +++ b/docs/src/developers_guide/release.rst @@ -126,9 +126,8 @@ These steps assume a release for ``v1.9`` is to be created. Release Steps ~~~~~~~~~~~~~ -#. Create the branch ``1.9.x`` on the main repo, not in a forked repo, for the - release candidate or release. The only exception is for a point/bugfix - release as it should already exist +#. Create the release feature branch ``1.9.x`` on `SciTools/iris`_. + The only exception is for a point/bugfix release, as it should already exist #. Update the ``iris.__init__.py`` version string e.g., to ``1.9.0`` #. Update the what's new for the release: @@ -175,4 +174,5 @@ Post Release Steps .. _Read The Docs: https://readthedocs.org/projects/scitools-iris/builds/ +.. _SciTools/iris: https://github.com/SciTools/iris .. _tag on the SciTools/Iris: https://github.com/SciTools/iris/releases From 2507017a95aec220e2430a72b2ad487decbfa945 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Fri, 5 Feb 2021 22:05:09 +0000 Subject: [PATCH 5/5] review actions --- docs/src/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index f8941a80fc..30e6150b39 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -96,7 +96,7 @@ def autolog(message): # Create a variable that can be inserted in the rst "|copyright_years|". # You can add more variables here if needed. rst_epilog = f""" -.. |copyright_years| replace:: {2010 - upper_copy_year} +.. |copyright_years| replace:: 2010 - {upper_copy_year} .. |python_version| replace:: {'.'.join([str(i) for i in sys.version_info[:3]])} .. |iris_version| replace:: v{version} .. |build_date| replace:: ({datetime.datetime.now().strftime('%d %b %Y')})