From bcb5b3ddabe08f03fdf2b25f1aac95985e77edbc Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 17:50:57 +0100 Subject: [PATCH 01/10] Initial setup for towncrier, absorbing one existing item. --- .gitignore | 1 + docs/Makefile | 5 ++++- docs/change_log.rst | 13 ++++--------- docs/changelog_fragments/.gitignore | 1 + docs/changelog_fragments/123.feat.rst | 1 + pyproject.toml | 28 +++++++++++++++++++++++++++ 6 files changed, 39 insertions(+), 10 deletions(-) create mode 100644 docs/changelog_fragments/.gitignore create mode 100644 docs/changelog_fragments/123.feat.rst diff --git a/.gitignore b/.gitignore index 3fc4714..f38462c 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,4 @@ coverage.xml # Docs docs/_build docs/api +docs/details/api diff --git a/docs/Makefile b/docs/Makefile index 660a397..94ad5c1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,9 +18,12 @@ allapi: rm -rf ./details/api sphinx-apidoc -Mfe -o ./details/api ../lib/ncdata +towncrier: + towncrier build --yes + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile allapi +%: Makefile allapi towncrier @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) view: diff --git a/docs/change_log.rst b/docs/change_log.rst index 97304d1..7efee7c 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -23,16 +23,11 @@ Change Notes ------------ Summary of key features by release number - -pending-unreleased -^^^^^^^^^^^^^^^^^^ -* `@pp-mo`_ Added linkcheck action, weekdays at 0800 - (`PR#123 `_), - (`PR#125 `_). +.. towncrier release notes start v0.2.0 -^^^^^^ +====== Overhauled data manipulation APIs. Expanded and improved documentation. * `@pp-mo`_ Reviewed, corrected, reorganised and expanded all documentation. @@ -71,7 +66,7 @@ Overhauled data manipulation APIs. Expanded and improved documentation. v0.1.1 -^^^^^^ +====== Small tweaks + bug fixes. **Note:** `PR#62 `_, and `PR#59 `_ are important fixes to @@ -94,7 +89,7 @@ i.e. moving arbitrarily large data via Dask without running out of memory. v0.1.0 -^^^^^^ +====== First release `v0.1.0 on GitHub `_ diff --git a/docs/changelog_fragments/.gitignore b/docs/changelog_fragments/.gitignore new file mode 100644 index 0000000..f935021 --- /dev/null +++ b/docs/changelog_fragments/.gitignore @@ -0,0 +1 @@ +!.gitignore diff --git a/docs/changelog_fragments/123.feat.rst b/docs/changelog_fragments/123.feat.rst new file mode 100644 index 0000000..053d2cd --- /dev/null +++ b/docs/changelog_fragments/123.feat.rst @@ -0,0 +1 @@ +Added regular linkcheck gha. diff --git a/pyproject.toml b/pyproject.toml index aae8f6f..b1a32c4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -82,3 +82,31 @@ include = '\.pyi?$' [tool.isort] line_length = "79" profile = "black" + +[tool.towncrier] +package = "ncdata" +package_dir = "lib" +directory = "docs/changelog_fragments" +filename = "docs/change_log.rst" +issue_format = "`ISSUE#{issue} `_" + +[[tool.towncrier.type]] +directory = "feat" +name = "Features" +showcontent = true + +[[tool.towncrier.type]] +directory = "doc" +name = "Documentation changes" +showcontent = true + +[[tool.towncrier.type]] +directory = "bug" +name = "Bug Fixes" +showcontent = true + +[[tool.towncrier.type]] +directory = "dev" +name = "Developer and Internal changes" +showcontent = true + From 2504165618c6d026f9fe677874bcc2fc1ed43c21 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 18:12:23 +0100 Subject: [PATCH 02/10] Add own fragment. --- docs/changelog_fragments/116.dev.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/changelog_fragments/116.dev.txt diff --git a/docs/changelog_fragments/116.dev.txt b/docs/changelog_fragments/116.dev.txt new file mode 100644 index 0000000..f3bda00 --- /dev/null +++ b/docs/changelog_fragments/116.dev.txt @@ -0,0 +1 @@ +Switch to towncrier for whats-new management. From 21abe9edeb1d8802fe1bee8c146354abe3b07bdf Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 18:36:13 +0100 Subject: [PATCH 03/10] Cover towncrier in developer notes. Incr dev notes. --- docs/change_log.rst | 26 ++++++++++++++++++++++++++ docs/details/developer_notes.rst | 21 ++++++++++++++++----- 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/docs/change_log.rst b/docs/change_log.rst index 7efee7c..ba72f11 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -25,6 +25,32 @@ Summary of key features by release number .. towncrier release notes start +Ncdata 0.3.0.dev4+dirty (2025-07-28) +==================================== + +No significant changes. + + +Ncdata 0.3.0.dev4+dirty (2025-07-28) +==================================== + +No significant changes. + + +Ncdata 0.3.0.dev4+dirty (2025-07-28) +==================================== + +Features +-------- + +- Added regular linkcheck gha. (`ISSUE#123 `_) + + +Developer and Internal changes +------------------------------ + +- Switch to towncrier for whats-new management. (`ISSUE#116 `_) + v0.2.0 ====== diff --git a/docs/details/developer_notes.rst b/docs/details/developer_notes.rst index 7271394..9b9d1cd 100644 --- a/docs/details/developer_notes.rst +++ b/docs/details/developer_notes.rst @@ -5,11 +5,19 @@ Maintenance and manual processes Change Log Maintenance ---------------------- -For now, development PRs should normally include additions in the common -changelog file ``docs/change_log.rst``. +Change log entries are now managed with `towncrier `_. -For now, we aren't categorising changes, but intend to include a combination -of release-page notes and a simple list of PRs. +A new change-note fragment file should be included in each PR, but is normally created +with a ``towncrier`` command-line command: + +* shortly, with ``towncrier create --content "mynotes..." ..rst`` +* ... or for longer forms, use ``towncrier create --edit``. +* Here, "" is one of feat/doc/bug/dev/misc. Which are: user features; + bug fixes; documentation changes; general developer-relevant changes; + or "miscellaneous". + (For reference, these categories are configured in ``pyproject.toml``). +* fragments live in ``docs/changelog_fragments``. +* N.B. for this to work well, every change should link to a github issue. Documentation build @@ -18,6 +26,8 @@ Documentation build * For a full docs-build * a simple ``$ make html`` will do for now * The ``docs/Makefile`` wipes the API docs and invokes sphinx-apidoc for a full rebuild + * It also calls towncrier to clear out the changelog fragments + update ``docs/change_log.rst``. + This should be reverted before pushing your PR -- i.e. leave changenotes in the fragments. * Results are then available at ``docs/_build/html/index.html`` * The above is just for *local testing* if required @@ -30,7 +40,8 @@ Release actions #. Update the :ref:`change_log` page in the details section - #. ensure all major changes + PRs are referenced in the :ref:`change_notes` section + #. ensure all major changes + PRs are referenced in the :ref:`change_notes` section. + The starting point for this is now just : ``towncrier build``. #. update the "latest version" stated in the :ref:`development_status` section From 2603922aa1f4b37e26dcda01c452ab8a1edc148a Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 18:37:31 +0100 Subject: [PATCH 04/10] Align changelog section levels with enclosing docs. --- docs/change_log.rst | 37 ++++--------------------------------- pyproject.toml | 6 ++++++ 2 files changed, 10 insertions(+), 33 deletions(-) diff --git a/docs/change_log.rst b/docs/change_log.rst index ba72f11..c7628e3 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -19,41 +19,12 @@ The code is however still experimental, and APIs are not stable .. _change_notes: -Change Notes ------------- -Summary of key features by release number +Summary of key features by release number: .. towncrier release notes start -Ncdata 0.3.0.dev4+dirty (2025-07-28) -==================================== - -No significant changes. - - -Ncdata 0.3.0.dev4+dirty (2025-07-28) -==================================== - -No significant changes. - - -Ncdata 0.3.0.dev4+dirty (2025-07-28) -==================================== - -Features --------- - -- Added regular linkcheck gha. (`ISSUE#123 `_) - - -Developer and Internal changes ------------------------------- - -- Switch to towncrier for whats-new management. (`ISSUE#116 `_) - - v0.2.0 -====== +~~~~~~ Overhauled data manipulation APIs. Expanded and improved documentation. * `@pp-mo`_ Reviewed, corrected, reorganised and expanded all documentation. @@ -92,7 +63,7 @@ Overhauled data manipulation APIs. Expanded and improved documentation. v0.1.1 -====== +~~~~~~ Small tweaks + bug fixes. **Note:** `PR#62 `_, and `PR#59 `_ are important fixes to @@ -115,7 +86,7 @@ i.e. moving arbitrarily large data via Dask without running out of memory. v0.1.0 -====== +~~~~~~ First release `v0.1.0 on GitHub `_ diff --git a/pyproject.toml b/pyproject.toml index b1a32c4..0c7bb8f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -89,6 +89,7 @@ package_dir = "lib" directory = "docs/changelog_fragments" filename = "docs/change_log.rst" issue_format = "`ISSUE#{issue} `_" +underlines = ["~", "^", "*", "+"] [[tool.towncrier.type]] directory = "feat" @@ -110,3 +111,8 @@ directory = "dev" name = "Developer and Internal changes" showcontent = true +[[tool.towncrier.type]] +directory = "misc" +name = "Developer and Internal changes" +showcontent = true + From ec4b8736b8e52d615e1b69f95d59e1791b112393 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 23:16:42 +0100 Subject: [PATCH 05/10] Added whatsnew for older PR 131. --- docs/changelog_fragments/131.feat.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/changelog_fragments/131.feat.rst diff --git a/docs/changelog_fragments/131.feat.rst b/docs/changelog_fragments/131.feat.rst new file mode 100644 index 0000000..9bc2ee5 --- /dev/null +++ b/docs/changelog_fragments/131.feat.rst @@ -0,0 +1,2 @@ +Make `to_iris` use the full iris load processing, instead of netcdf load_cubes. +This means you can use load controls such as callbacks and constraints. From 9a83c38b4750c8fd314d7072678e3b2195da92e8 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 23:37:07 +0100 Subject: [PATCH 06/10] Add towncrier into RTD build config. --- .readthedocs.yml | 1 + requirements/readthedocs.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 7bfd104..8c77c7d 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -20,6 +20,7 @@ build: - git stash post_install: - sphinx-apidoc -Mfe -o ./docs/api ./lib/ncdata + - towncrier build --yes - git stash pop conda: diff --git a/requirements/readthedocs.yml b/requirements/readthedocs.yml index 520e71a..cc80ea0 100644 --- a/requirements/readthedocs.yml +++ b/requirements/readthedocs.yml @@ -15,4 +15,5 @@ dependencies: - python<3.13 - sphinx - sphinxcontrib-napoleon + - towncrier - xarray From 02eb243346c2616619f9d331a382e00b1f6609c0 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 23:45:14 +0100 Subject: [PATCH 07/10] Adjust #131 whatsnew. --- docs/changelog_fragments/131.feat.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/changelog_fragments/131.feat.rst b/docs/changelog_fragments/131.feat.rst index 9bc2ee5..1fa54a2 100644 --- a/docs/changelog_fragments/131.feat.rst +++ b/docs/changelog_fragments/131.feat.rst @@ -1,2 +1,3 @@ -Make `to_iris` use the full iris load processing, instead of netcdf load_cubes. +Make :meth:`~ncdata.iris.to_iris` use the full iris load processing, +instead of :meth:`iris.fileformats.netcdf.loader.load_cubes`. This means you can use load controls such as callbacks and constraints. From 6e1a1676003f1a7693060c382452aad33fb510a6 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 28 Jul 2025 23:54:36 +0100 Subject: [PATCH 08/10] Improve developer notes. --- docs/change_log.rst | 18 +++++++++++ docs/changelog_fragments/116.dev.txt | 1 - docs/changelog_fragments/123.feat.rst | 1 - docs/changelog_fragments/131.feat.rst | 3 -- docs/details/developer_notes.rst | 43 ++++++++++++++++++--------- 5 files changed, 47 insertions(+), 19 deletions(-) delete mode 100644 docs/changelog_fragments/116.dev.txt delete mode 100644 docs/changelog_fragments/123.feat.rst delete mode 100644 docs/changelog_fragments/131.feat.rst diff --git a/docs/change_log.rst b/docs/change_log.rst index c7628e3..d036cce 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -23,6 +23,24 @@ Summary of key features by release number: .. towncrier release notes start +Ncdata 0.3.0.dev4+dirty (2025-07-29) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Features +^^^^^^^^ + +- Added regular linkcheck gha. (`ISSUE#123 `_) +- Make :meth:`~ncdata.iris.to_iris` use the full iris load processing, + instead of :meth:`iris.fileformats.netcdf.loader.load_cubes`. + This means you can use load controls such as callbacks and constraints. (`ISSUE#131 `_) + + +Developer and Internal changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Switch to towncrier for whats-new management. (`ISSUE#116 `_) + + v0.2.0 ~~~~~~ Overhauled data manipulation APIs. Expanded and improved documentation. diff --git a/docs/changelog_fragments/116.dev.txt b/docs/changelog_fragments/116.dev.txt deleted file mode 100644 index f3bda00..0000000 --- a/docs/changelog_fragments/116.dev.txt +++ /dev/null @@ -1 +0,0 @@ -Switch to towncrier for whats-new management. diff --git a/docs/changelog_fragments/123.feat.rst b/docs/changelog_fragments/123.feat.rst deleted file mode 100644 index 053d2cd..0000000 --- a/docs/changelog_fragments/123.feat.rst +++ /dev/null @@ -1 +0,0 @@ -Added regular linkcheck gha. diff --git a/docs/changelog_fragments/131.feat.rst b/docs/changelog_fragments/131.feat.rst deleted file mode 100644 index 1fa54a2..0000000 --- a/docs/changelog_fragments/131.feat.rst +++ /dev/null @@ -1,3 +0,0 @@ -Make :meth:`~ncdata.iris.to_iris` use the full iris load processing, -instead of :meth:`iris.fileformats.netcdf.loader.load_cubes`. -This means you can use load controls such as callbacks and constraints. diff --git a/docs/details/developer_notes.rst b/docs/details/developer_notes.rst index 9b9d1cd..4f98e73 100644 --- a/docs/details/developer_notes.rst +++ b/docs/details/developer_notes.rst @@ -16,22 +16,26 @@ with a ``towncrier`` command-line command: bug fixes; documentation changes; general developer-relevant changes; or "miscellaneous". (For reference, these categories are configured in ``pyproject.toml``). -* fragments live in ``docs/changelog_fragments``. -* N.B. for this to work well, every change should link to a github issue. +* the fragment files are stored in ``docs/changelog_fragments``. +* N.B. for this to work well, every change should be identified with a matching github issue. + If there are multiple associated PRs, they should all be linked to the issue. Documentation build ------------------- -* For a full docs-build - * a simple ``$ make html`` will do for now - * The ``docs/Makefile`` wipes the API docs and invokes sphinx-apidoc for a full rebuild - * It also calls towncrier to clear out the changelog fragments + update ``docs/change_log.rst``. - This should be reverted before pushing your PR -- i.e. leave changenotes in the fragments. +For a full docs-build: -* Results are then available at ``docs/_build/html/index.html`` - * The above is just for *local testing* if required - * We have automatic builds for releases and PRs +* a simple ``$ make html`` will do for now +* The ``docs/Makefile`` wipes the API docs and invokes sphinx-apidoc for a full rebuild +* It also calls towncrier to clear out the changelog fragments + update ``docs/change_log.rst``. + This should be reverted before pushing your PR -- i.e. leave changenotes in the fragments. +* the results is then available at ``docs/_build/html/index.html``. + +.. note:: + + * the above is just for *local testing*, if required. + * For PRs (and releases), we also provide *automatic* builds on GitHub, via `ReadTheDocs `_ @@ -41,11 +45,14 @@ Release actions #. Update the :ref:`change_log` page in the details section #. ensure all major changes + PRs are referenced in the :ref:`change_notes` section. - The starting point for this is now just : ``towncrier build``. + + * The starting point for this is now just : ``$ towncrier build``. #. update the "latest version" stated in the :ref:`development_status` section -#. Cut a release on GitHub : this triggers a new docs version on [ReadTheDocs](https://readthedocs.org/projects/ncdata/) +#. Cut a release on GitHub + + * this triggers a new docs version on `ReadTheDocs `_. #. Build the distribution @@ -58,39 +65,47 @@ Release actions #. if needed, get `twine `_ #. run + * ``$ python -m twine upload --repository testpypi dist/*`` * this uploads to TestPyPI #. create a new env with test dependencies + * ``$ conda create -n ncdtmp python=3.11 iris xarray filelock requests pytest pip`` - * ( N.B. 'filelock' and 'requests' are _test_ dependencies of iris ) + * ( N.B. 'filelock' and 'requests' are *test dependencies* of iris ) #. install the new package with + * ``$ pip install --index-url https://test.pypi.org/simple/ ncdata`` * ..and run tests #. if that checks OK, + * **remove** ``--repository testpypi`` **and repeat** "upload" step (2) * --> uploads to "real" PyPI #. repeat "pip install" step (4) + * but **removing** the ``--index-url`` * ..to check that ``pip install ncdata`` now finds the new version #. Update conda to source the new version from PyPI #. create a PR on the `ncdata feedstock `_ - #. update : + * `version number `_ * `SHA `_ * Notes: + * the `PyPI reference `_ will normally look after itself * also at this point + * make any required changes to `dependencies `_ * ..but normally, **no** changes will be required #. get PR merged + * wait a few hours.. * check that the new version appears in the output of ``$ conda search ncdata`` From e3ccdde26ab5b396e6cd1bb6d6270575bc212bc1 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Tue, 29 Jul 2025 00:12:48 +0100 Subject: [PATCH 09/10] Replace changelog parts. --- docs/change_log.rst | 18 ------------------ docs/changelog_fragments/116.dev.txt | 1 + docs/changelog_fragments/123.feat.rst | 1 + docs/changelog_fragments/131.feat.rst | 3 +++ 4 files changed, 5 insertions(+), 18 deletions(-) create mode 100644 docs/changelog_fragments/116.dev.txt create mode 100644 docs/changelog_fragments/123.feat.rst create mode 100644 docs/changelog_fragments/131.feat.rst diff --git a/docs/change_log.rst b/docs/change_log.rst index d036cce..c7628e3 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -23,24 +23,6 @@ Summary of key features by release number: .. towncrier release notes start -Ncdata 0.3.0.dev4+dirty (2025-07-29) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Features -^^^^^^^^ - -- Added regular linkcheck gha. (`ISSUE#123 `_) -- Make :meth:`~ncdata.iris.to_iris` use the full iris load processing, - instead of :meth:`iris.fileformats.netcdf.loader.load_cubes`. - This means you can use load controls such as callbacks and constraints. (`ISSUE#131 `_) - - -Developer and Internal changes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- Switch to towncrier for whats-new management. (`ISSUE#116 `_) - - v0.2.0 ~~~~~~ Overhauled data manipulation APIs. Expanded and improved documentation. diff --git a/docs/changelog_fragments/116.dev.txt b/docs/changelog_fragments/116.dev.txt new file mode 100644 index 0000000..f3bda00 --- /dev/null +++ b/docs/changelog_fragments/116.dev.txt @@ -0,0 +1 @@ +Switch to towncrier for whats-new management. diff --git a/docs/changelog_fragments/123.feat.rst b/docs/changelog_fragments/123.feat.rst new file mode 100644 index 0000000..053d2cd --- /dev/null +++ b/docs/changelog_fragments/123.feat.rst @@ -0,0 +1 @@ +Added regular linkcheck gha. diff --git a/docs/changelog_fragments/131.feat.rst b/docs/changelog_fragments/131.feat.rst new file mode 100644 index 0000000..1fa54a2 --- /dev/null +++ b/docs/changelog_fragments/131.feat.rst @@ -0,0 +1,3 @@ +Make :meth:`~ncdata.iris.to_iris` use the full iris load processing, +instead of :meth:`iris.fileformats.netcdf.loader.load_cubes`. +This means you can use load controls such as callbacks and constraints. From bad6b63ebc823e5059f1edf311466342164de6d2 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Tue, 29 Jul 2025 00:27:49 +0100 Subject: [PATCH 10/10] Small fix to api docstring. --- lib/ncdata/iris.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/lib/ncdata/iris.py b/lib/ncdata/iris.py index 5651a4b..536a8cd 100644 --- a/lib/ncdata/iris.py +++ b/lib/ncdata/iris.py @@ -38,7 +38,7 @@ def to_iris( object(s) to be loaded into Iris, treated as equivalent to netCDF4 datasets. iris_load_kwargs : dict - extra keywords, passed to :func:`iris.fileformats.netcdf.load_cubes` + extra keywords, passed into the :func:`iris.load` call. Returns ------- @@ -66,13 +66,18 @@ def from_iris( cubes : :class:`iris.cube.Cube`, or iterable of Cubes cube or cubes to "save" to an NcData object. iris_save_kwargs : dict - additional keys passed to :func:`iris.fileformats.netcdf.save` operation. + additional keys passed into the :func:`iris.save` call. Returns ------- ncdata : NcData output data created from saving ``cubes`` + Notes + ----- + The keys "compute" and "saver" must not appear in ``iris_save_kwargs``, + as these these are already used. + """ nc4like = Nc4DatasetLike() delayed = iris.save(