Adopt towncrier

.gitignore

@@ -45,3 +45,4 @@ coverage.xml
 # Docs
 docs/_build
 docs/api
+docs/details/api

.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:

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:

docs/change_log.rst

@@ -19,20 +19,12 @@ The code is however still experimental, and APIs are not stable
 
 .. _change_notes:
 
-Change Notes
-------------
-Summary of key features by release number
-
-
-pending-unreleased
-^^^^^^^^^^^^^^^^^^
-* `@pp-mo`_ Added linkcheck action, weekdays at 0800
-  (`PR#123 <https://github.com/pp-mo/ncdata/pull/123>`_),
-  (`PR#125 <https://github.com/pp-mo/ncdata/pull/125>`_).
+Summary of key features by release number:
 
+.. 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 +63,7 @@ Overhauled data manipulation APIs.  Expanded and improved documentation.
 
 
 v0.1.1
-^^^^^^
+~~~~~~
 Small tweaks + bug fixes.
 **Note:** `PR#62 <https://github.com/pp-mo/ncdata/pull/62>`_, and 
 `PR#59 <https://github.com/pp-mo/ncdata/pull/59>`_ are important fixes to
@@ -94,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 <https://github.com/pp-mo/ncdata/releases/tag/v0.1.0>`_

docs/changelog_fragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

docs/changelog_fragments/116.dev.txt

@@ -0,0 +1 @@
+Switch to towncrier for whats-new management.

docs/changelog_fragments/123.feat.rst

@@ -0,0 +1 @@
+Added regular linkcheck gha.

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.

docs/details/developer_notes.rst

@@ -5,23 +5,37 @@ 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 <https://towncrier.readthedocs.io/en/stable/>`_.
 
-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..." <ISSUE-num>.<category>.rst``
+* ... or for longer forms, use ``towncrier create --edit``.
+* Here, "<category>" 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``).
+* 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
+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.
+* the results is then available at ``docs/_build/html/index.html``.
 
-* 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
+.. note::
+
+    * the above is just for *local testing*, if required.
+    * For PRs (and releases), we also provide *automatic* builds on GitHub,
       via `ReadTheDocs <https://readthedocs.org/projects/ncdata/>`_
 
 
@@ -30,11 +44,15 @@ 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
 
-#. 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 <https://readthedocs.org/projects/ncdata>`_.
 
 #. Build the distribution
 
@@ -47,39 +65,47 @@ Release actions
     #. if needed, get `twine <https://github.com/pypa/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 <https://github.com/conda-forge/ncdata-feedstock>`_
-
     #. update :
+
         * `version number <https://github.com/conda-forge/ncdata-feedstock/blob/3f6b35cbdffd2ee894821500f76f2b0b66f55939/recipe/meta.yaml#L2>`_
         * `SHA <https://github.com/conda-forge/ncdata-feedstock/blob/3f6b35cbdffd2ee894821500f76f2b0b66f55939/recipe/meta.yaml#L10>`_
         * Notes:
+
             * the `PyPI reference <https://github.com/conda-forge/ncdata-feedstock/blob/3f6b35cbdffd2ee894821500f76f2b0b66f55939/recipe/meta.yaml#L9>`_
               will normally look after itself
             * also at this point
+
                * make any required changes to `dependencies <https://github.com/conda-forge/ncdata-feedstock/blob/3f6b35cbdffd2ee894821500f76f2b0b66f55939/recipe/meta.yaml#L17-L29>`_
                * ..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``

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(

pyproject.toml

@@ -82,3 +82,37 @@ 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} <https://github.com/pp-mo/ncdata/pull/{issue}>`_"
+underlines = ["~", "^", "*", "+"]
+
+[[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
+
+[[tool.towncrier.type]]
+directory = "misc"
+name = "Developer and Internal changes"
+showcontent = true
+

requirements/readthedocs.yml

@@ -15,4 +15,5 @@ dependencies:
   - python<3.13
   - sphinx
   - sphinxcontrib-napoleon
+  - towncrier
   - xarray