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/.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/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..c7628e3 100644 --- a/docs/change_log.rst +++ b/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 `_), - (`PR#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 `_, and `PR#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 `_ 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/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. diff --git a/docs/details/developer_notes.rst b/docs/details/developer_notes.rst index 7271394..4f98e73 100644 --- a/docs/details/developer_notes.rst +++ b/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 `_. -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``). +* 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 `_ @@ -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 `_. #. Build the distribution @@ -47,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`` 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( diff --git a/pyproject.toml b/pyproject.toml index aae8f6f..0c7bb8f 100644 --- a/pyproject.toml +++ b/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} `_" +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 + 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