[pp-mo]

Purposes :

• reorganise the _templating_include.json in mostly-alphabetical order
• add a template for ci-template-checks.json , which several repos have a near-identical version of, but was not templated yet
• add a template for run_doctests.py, the new doctest runner tool

near-alphabetic ordering
_templating_include.json has a mapping form, where each key is the name of a file in the templates directory (or subdirs).
Existing content was not in a standard order, making it hard to find things.
This is now fixed, with "comments" added to explain (and added ability to skip comments when reading)

ci-template-checks
Various repos already have a copy of this.
It issues a reminder to check the master template when a PR modifies a templated file.
This PR provides a central templated version of it, based on the version currently in Iris.
The Iris one seems to be the most highly developed form, with more recent changes to satisfy zizmor

run_doctests
This is intended to replace "sphinx doctest"

• faster and more flexible as it doesn't use sphinx
  • see https://github.com/SciTools/run-doctests
• but may require some re-formatting of doctest setup/teardown sections, if they are in sphinx-specific format (as in Iris)
• ready to use in ncdata, hopefully coming to Iris later

[Copilot]

🟡 Changes recommended

The doctest runner can falsely succeed without running tests and mishandles a valueless options argument.

4 open findings

• Combine duplicate comment keys · New
• Fail when glob expansion finds no files · New
• Correct the documented workflow filename · New
• Remove the obsolete utility TODO · New

What changed in this PR

Adds reusable CI and doctest templates while reorganizing the template registry.

Changes:

• Adds doctest runner and template-check workflow templates.
• Reorders and expands template mappings.
• Adds comment-entry support and documentation.

File	Description
templates/​run_doctests.py	Adds the doctest runner.
templates/​README.md	Documents template-check workflows.
templates/​github/​workflows/​ci-template-check.yml	Adds the reusable workflow caller.
templates/​_templating_scripting.py	Skips configuration comments.
templates/​_templating_include.json	Reorders mappings and registers new templates.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[pp-mo]

Note

when this is merged, I'll be interested to see what update issues may be posted on various repos.
I also intend to post-edit 'run_doctests.py', just to change the module docstring, and that should prompt ncdata, iris (maybe) and run-doctests repos.

[stephenworsley]

Looks good, just a couple comments to raise, mainly a concern about handling of private modules.

[stephenworsley]

Took me a minute to realise this was targeting an outside repo. More I'm more flagging this as something to be aware of than something to fix, but having repos named ".github" and "workflows" can get a bit confusing when they start referencing each other like this.

[pp-mo]

As stated, this content is identical to what's in Iris.
Actually it's like this in iris/stratify/nc-time-axis, and a slightly older version in iris-grib/iris-esmf-regrid/tephi/cf-units/mo-pack

The use of 'workflows' is kind-of deprecated + supposed to be replaced by templating.
In this case, it should be possible to replace the composite action with actions code in the template, and share that with whatever changes (like project name).
But it's not trivial so I'm avoiding doing that here + now.

[stephenworsley]

will this approach exclude docstrings on objects which are defined in an __init__.py or in private modules but are imported as public objects into public modules?

[pp-mo]

To answer the exact question, this does not affect the private/public nature of objects in a module, because we are only scanning module paths (and excluding private ones) : When a module sourcefile is checked, the whole of its source is scanned by doctest, and the existence of API objects is irrelevant, since that discovery does not use any import or inspection mechanism -- it just operates on the Python source content as raw text.
(That may be different for Sphinx, IIUC).

---

However...
there is a related question of a private module exposed as a public 'alias'.
I "assumed" this would be OK because it is using the module import discovery mechanism to find the files to check, so if a module is private but there is a public-named version of it re-exported, it will get tested under the public name / module path.

However, when I tested that idea, I found that the Python definition of an importable 'module' doesn't actually work the way I thought.
For example:

• in a "testextra/__init__.py" : from . import _private_mod as public_mod
• then

$ python -c "import testextra._private_mod as m; print(m)"
<module 'testextra._private_mod' from ...>

$ python -c "import testextra.public_mod as m; print(m)"
Traceback ...
ModuleNotFoundError: No module named 'testextra.public_mod'

.. but ..

$ python -c "from ncdata.testextra import public_mod as m; print(m)"
<module 'testextra._private_mod' from ... >

---

Meanwhile, I have now also realised that, when object (e.g. class) definitions are specifically imported from a private submodule and re-exported as public definitions (e.g. : ncdata.NcData is really ncdata._core.NcData),
of course any doctests on those things occur in the private submodule sourcefile, and so won't be tested.
( For example,
content in ncdata._core has 15 doctests, but although the core classes are 'published' as properties of the ncdata module, those tests won't be covered by run_doctests.py -mrp ncdata.
)

So, reluctantly, I'm now thinking that the `--public_only`` keyword is effectively useless + should be removed

Do you have anything more to suggest?
If not I'll simplify that away.

[stephenworsley]

This sounds about right to me, removing the --public_only keyword sounds like the cleanest way of resolving this.