Pytestless doctests

.github/workflows/ci-tests.yml

@@ -83,11 +83,9 @@ jobs:
       - name: "Run doctests: Docs"
         if: matrix.session == 'doctests-docs'
         run: |
-          cd docs
-          pytest --doctest-glob="*.rst" --doctest-continue-on-failure
+          tools/run_doctests.py -v "./docs/**/*.rst"
 
       - name: "Run doctests: API"
         if: matrix.session == 'doctests-api'
         run: |
-          cd lib
-          pytest --doctest-modules --doctest-continue-on-failure
+          tools/run_doctests.py -v -mr ncdata

docs/Makefile

@@ -19,8 +19,7 @@ allapi:
 	sphinx-apidoc -Mfe -o ./details/api ../lib/ncdata
 
 towncrier:
-	if [ -e changelog_fragments/*.rst ]; then towncrier build --yes; fi
-
+	if [[ "$$(ls changelog_fragments)" != "" ]]; then towncrier build --yes; fi
 
 # Tweaked "make html", which restores the changelog state after docs build.
 html-keeplog: html

docs/changelog_fragments/173.dev.rst

@@ -0,0 +1 @@
+Fix xarray 2025.09.1 problem.

docs/changelog_fragments/174.doc.rst

@@ -0,0 +1 @@
+Document how to create a developer installation.

docs/changelog_fragments/175.dev.rst

@@ -0,0 +1 @@
+Pinned python for now, since 3.14 causes problems with Iris (notably).

docs/details/developer_notes.rst

@@ -19,7 +19,7 @@ with a ``towncrier`` command-line command:
     * "feat": user features
     * "doc": documentation changes
     * "bug": bug fixes
-    * "def": general developer-relevant changes
+    * "dev": general developer-relevant changes
     * "misc": miscellaneous
 
   (For reference, these categories are configured in ``pyproject.toml``).
@@ -29,6 +29,19 @@ with a ``towncrier`` command-line command:
 * 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.
 
+.. _developer_install:
+
+Developer Installation
+----------------------
+For an editable installation, make a Python environment containing at least **numpy,
+netCDF4, dask and pip**.  It is also highly recommended to get
+`towncrier <https://github.com/twisted/towncrier>`_ and
+`pre-commit <https://github.com/pre-commit/pre-commit>`_.
+(and enable pre-commit with ``$ pre-commit install``).
+
+Then, cd to your checkout, and ``$ pip install -e .``.
+This should result in an editable development installation.
+
 
 Documentation build
 -------------------
@@ -83,7 +96,7 @@ Release actions
 
     #. create a new env with test dependencies
 
-       * ``$ conda create -n ncdtmp python=3.11 iris xarray filelock requests pytest pip``
+       * ``$ conda create -n ncdtmp python=3.13 iris xarray filelock requests pytest pip``
        * ( N.B. 'filelock' and 'requests' are *test dependencies* of iris )
 
     #. install the new package with

docs/userdocs/getting_started/installation.rst

@@ -29,3 +29,8 @@ Check install
     <NcData: <'no-name'>
     >
 
+
+Developer Installation
+----------------------
+To work on changes to the ncdata code, you will need an "editable installation".
+See : :ref:`developer_install`.

docs/userdocs/getting_started/introduction.rst

@@ -40,7 +40,7 @@ and :attr:`~ncdata.NcData.attributes`:
     >>> data
     <ncdata._core.NcData object at ...>
     >>> print(data)
-    <NcData: myname
+    <NcData: urrgh
     >
 
     >>> dim = NcDimension("x", 3)

lib/ncdata/utils/_dim_indexing.py

@@ -34,7 +34,7 @@ def index_by_dimensions(
         >>> data = NcData(dimensions=[NcDimension(nn, 10) for nn in ("time", "levels")])
 
     >>> data1 = index_by_dimensions(data, time=slice(0, 10))  # equivalent to [:10]
-    >>> data2 = index_by_dimensions(data, levels=[1,2,5])
+    >>> data2 = index_by_dimension(data, levels=[1,2,5])
     >>> data3 = index_by_dimensions(data, time=3, levels=slice(2, 10, 3))
 
     Notes

tools/check_doctest.py

@@ -0,0 +1,29 @@
+from doctest import ELLIPSIS as ELLIPSIS_FLAG
+from run_doctests import run_doctest_paths, _parser, parserargs_as_kwargs
+
+# tstargs = ['ncdata', '-da', '--options', 'verbose=1']
+
+# tstargs = [
+#     "/home/users/patrick.peglar/git/ncdata/docs/userdocs/user_guide/howtos.rst",
+#     "--options",
+#     "verbose=1",
+# ]
+
+# tstargs = ["-mvr", "iris.coords", "-o", "verbose=True"]
+
+# tstargs = ["-mvr", "iris.tests.unit.fileformats.netcdf", "-e", "attribute_handlers"]
+
+tstargs = ["-mvr", "iris._combine", "-o", "raise_on_error=True"]
+
+tstargs = ["-r", "../docs/userdocs/**/*.rst", "-e", "started.rst"]
+
+args = _parser.parse_args(tstargs)
+kwargs = parserargs_as_kwargs(args)
+# if not "options" in kwargs:
+#     kwargs["options"] = "ELLIPSIS=1"
+run_doctest_paths(**kwargs)
+
+#
+# Currently good:
+# $ tools/run_doctests.py docs/userdocs/getting_started/introduction.rst -o "optionflags=8"
+# $ tools/run_doctests.py docs/userdocs/getting_started/*.rst -vo "optionflags=8"