API reference: detect missing class pages & populate all gaps

[sadielbartholomew]

We have a top-level script check_docs_api_coverage calling docs/source/check_docs_api_coverage.py to detect any udocumented methods and missing .rst stub files for the API Reference of the documentation, however it doesn't detect any classes which are present in the codebase which aren't documented, so whole classes and methods defined on them may be missed out.

This PR adds a check for missing classes to the script (excluding classes which represent our user-facing functions, emerging as docstring-substitution metaclasses) and then has used this to detect missing cases and added those in (turns out ~10 classes were missing).

As part of this, close #957.

Opening as a draft since I still have yet to sort:

• why the Domain class is not accessible/clickable;
• why the methods now listed on new class stub files for the previousy-missing classes are not yet accessible/clickable.

[sadielbartholomew]

OK now all sorted so opening for review. Notes:

why the Domain class is not accessible/clickable

It was a simple issue in the end, namely that we were auto-documenting the cfdm.Domain class instead of cf.Domain - probably as a copy and paste mistake. Now corrected in 5d5f6f7 which I can confirm fixes the broken interlink.

why the methods now listed on new class stub files for the previousy-missing classes are not yet accessible/clickable.

Not 100% sure what caused this, but with a fresh up-to-date sphinx environment using minimal pip installed libraries, all new pages and methods listed on them have working inter-linking as required, as tested with a ./release_docs dev-scrub build. For purposes of reproducibility I have pasted the conda env I used below.

Docs-building environment used

I set up a minimal env aiming to have just the docs building sphinx and extension libraries plus any dependencies of cf-python, as below.

Copy using e.g. conda env create -f env.yml on the below pasted as text into a file of that name:

name: cf-docs
channels:
  - conda-forge
  - defaults
dependencies:
  - _openmp_mutex=4.5=20_gnu
  - _python_abi3_support=1.0=hd8ed1ab_3
  - adwaita-icon-theme=49.0=unix_0
  - aiobotocore=3.8.0=pyhcf101f3_0
  - aiohappyeyeballs=2.7.1=pyhd8ed1ab_0
  - aiohttp=3.14.3=py312h5d8c7f2_0
  - aioitertools=0.13.0=pyhd8ed1ab_0
  - aiosignal=1.4.0=pyhd8ed1ab_0
  - alabaster=1.0.0=pyhd8ed1ab_1
  - aoo-mozilla-en-dict-au=2024.03.01=hd8ed1ab_1
  - aoo-mozilla-en-dict-ca=2024.03.01=hd8ed1ab_1
  - aoo-mozilla-en-dict-gb=2024.03.01=hd8ed1ab_1
  - aoo-mozilla-en-dict-us=2024.03.01=hd8ed1ab_1
  - aoo-mozilla-en-dict-za=2024.03.01=hd8ed1ab_1
  - at-spi2-atk=2.38.0=h0630a04_3
  - at-spi2-core=2.40.3=h0630a04_0
  - atk-1.0=2.38.0=h04ea711_2
  - attrs=26.1.0=pyhcf101f3_0
  - aws-c-auth=0.10.4=hb7a77c6_1
  - aws-c-cal=0.9.14=h2aa3ae6_4
  - aws-c-common=0.14.2=hb03c661_0
  - aws-c-compression=0.3.2=h720e601_4
  - aws-c-http=0.11.0=h38ae05a_4
  - aws-c-io=0.27.3=h6f4d18d_1
  - aws-c-s3=0.12.8=h46fcd08_1
  - aws-c-sdkutils=0.2.7=h720e601_2
  - aws-checksums=0.2.10=h720e601_4
  - babel=2.18.0=pyhcf101f3_1
  - backports.zstd=1.6.0=py312h90b7ffd_0
  - blosc=1.21.6=he440d0b_1
  - botocore=1.43.46=pyhd8ed1ab_0
  - brotli-python=1.2.0=py312hdb49522_1
  - bzip2=1.0.8=hda65f42_9
  - c-ares=1.34.8=hb03c661_0
  - ca-certificates=2026.7.22=hbd8a1cb_0
  - cached-property=1.5.2=hd8ed1ab_2
  - cached_property=1.5.2=pyha770c72_2
  - cairo=1.18.4=he90730b_1
  - certifi=2026.7.22=pyhd8ed1ab_0
  - cf-python=3.20.1=py312h3111c9b_0
  - cfdm=1.13.2.1=py312h7900ff3_0
  - cftime=1.6.5=py312h4f23490_1
  - cfunits=3.3.7=pyhd8ed1ab_1
  - charset-normalizer=3.4.9=pyhd8ed1ab_0
  - click=8.4.2=pyhc90fa1f_0
  - cloudpickle=3.1.2=pyhcf101f3_1
  - colorama=0.4.6=pyhd8ed1ab_1
  - cpython=3.12.13=py312hd8ed1ab_0
  - cytoolz=1.1.0=py312h4c3975b_2
  - dask-core=2026.7.1=pyhc364b38_0
  - dbus=1.16.2=h24cb091_1
  - deprecated=1.3.1=pyhd8ed1ab_1
  - distributed=2026.7.1=pyhc364b38_0
  - docutils=0.22.4=pyhd8ed1ab_0
  - donfig=0.8.1.post1=pyhd8ed1ab_1
  - enchant=2.8.2=h02132a2_0
  - epoxy=1.5.10=hb03c661_2
  - font-ttf-dejavu-sans-mono=2.37=hab24e00_0
  - font-ttf-inconsolata=3.000=h77eed37_0
  - font-ttf-source-code-pro=2.038=h77eed37_0
  - font-ttf-ubuntu=0.83=h77eed37_3
  - fontconfig=2.18.2=h27c8c51_0
  - fonts-conda-ecosystem=1=0
  - fonts-conda-forge=1=hc364b38_1
  - freetype=2.14.3=ha770c72_0
  - fribidi=1.0.16=hb03c661_0
  - frozenlist=1.8.0=py312h447239a_0
  - fsspec=2026.6.0=pyhd8ed1ab_0
  - gdk-pixbuf=2.44.7=h2b0a6b4_0
  - gettext=0.25.1=h3f43e3d_1
  - gettext-tools=0.25.1=h3f43e3d_1
  - glib=2.88.2=hbe0478d_0
  - glib-tools=2.88.2=h8094192_0
  - google-crc32c=1.8.0=py312h03f33d3_1
  - graphite2=1.3.15=hecca717_0
  - graphviz=14.1.2=h8b86629_0
  - gtk3=3.24.52=ha5ea40c_0
  - gts=0.7.6=h977cf35_4
  - h2=4.4.0=pyhcf101f3_0
  - h5netcdf=1.8.1=pyhd8ed1ab_0
  - h5py=3.16.0=nompi_py312ha829cd9_102
  - harfbuzz=14.2.1=ha770c72_1
  - hdf4=4.2.15=h2a13503_7
  - hdf5=2.1.0=nompi_h654f344_110
  - hicolor-icon-theme=0.17=ha770c72_3
  - hpack=4.2.0=pyhd8ed1ab_0
  - hunspell=1.7.2=h2a8d096_1
  - hunspell-en=2024.03.01=hd8ed1ab_1
  - hyperframe=6.1.0=pyhd8ed1ab_0
  - icu=78.3=h33c6efd_1
  - idna=3.18=pyhcf101f3_0
  - imagesize=2.0.0=pyhd8ed1ab_0
  - importlib-metadata=9.0.0=pyhcf101f3_0
  - jinja2=3.1.6=pyhcf101f3_1
  - jmespath=1.1.0=pyhcf101f3_1
  - keyutils=1.6.3=hb9d3cd8_0
  - krb5=1.22.2=hbde042b_1
  - ld_impl_linux-64=2.46.1=default_hbd61a6d_102
  - lerc=4.1.0=hdb68285_0
  - libaec=1.1.5=h088129d_0
  - libasprintf=0.25.1=h3f43e3d_1
  - libasprintf-devel=0.25.1=h3f43e3d_1
  - libblas=3.11.0=8_h4a7cf45_openblas
  - libcblas=3.11.0=8_h0358290_openblas
  - libcrc32c=1.1.2=h9c3ff4c_0
  - libcups=2.3.3=h7a8fb5f_6
  - libcurl=8.21.0=hae6b9f4_2
  - libdeflate=1.25=h17f619e_0
  - libdrm=2.4.127=hb03c661_0
  - libedit=3.1.20250104=pl5321h7949ede_0
  - libegl=1.7.0=ha4b6fd6_3
  - libegl-devel=1.7.0=ha4b6fd6_3
  - libev=4.33=hd590300_2
  - libexpat=2.8.1=hecca717_1
  - libffi=3.5.2=h3435931_0
  - libfreetype=2.14.3=ha770c72_0
  - libfreetype6=2.14.3=h73754d4_0
  - libgcc=15.2.0=he0feb66_19
  - libgcc-ng=15.2.0=h69a702a_19
  - libgd=2.3.3=h5fbf134_12
  - libgettextpo=0.25.1=h3f43e3d_1
  - libgettextpo-devel=0.25.1=h3f43e3d_1
  - libgfortran=15.2.0=h69a702a_19
  - libgfortran5=15.2.0=h68bc16d_19
  - libgl=1.7.0=ha4b6fd6_3
  - libgl-devel=1.7.0=ha4b6fd6_3
  - libglib=2.88.2=h0d30a3d_0
  - libglvnd=1.7.0=ha4b6fd6_3
  - libglx=1.7.0=ha4b6fd6_3
  - libglx-devel=1.7.0=ha4b6fd6_3
  - libgomp=15.2.0=he0feb66_19
  - libharfbuzz=14.2.1=h17a8019_1
  - libharfbuzz-devel=14.2.1=h17a8019_1
  - libiconv=1.18=h3b78370_2
  - libjpeg-turbo=3.2.0=hb03c661_0
  - liblapack=3.11.0=8_h47877c9_openblas
  - liblzma=5.8.3=hb03c661_0
  - libnetcdf=4.10.1=nompi_he3e3c8e_201
  - libnghttp2=1.68.1=h877daf1_0
  - libnsl=2.0.1=hb9d3cd8_1
  - libopenblas=0.3.33=pthreads_h94d23a6_0
  - libpciaccess=0.19=hb03c661_0
  - libpng=1.6.58=h421ea60_0
  - libpsl=0.22.0=h49b2146_1
  - librsvg=2.62.3=h4c96295_0
  - libsqlite=3.53.3=h0c1763c_0
  - libssh2=1.11.1=hcf80075_0
  - libstdcxx=15.2.0=h934c35e_19
  - libstdcxx-ng=15.2.0=hdf11a46_19
  - libtiff=4.7.2=h9d88235_0
  - libudunits2=2.2.28=h40f5838_3
  - libuuid=2.42.2=h5347b49_0
  - libwebp-base=1.6.0=hd42ef1d_0
  - libxcb=1.17.0=h8a09558_0
  - libxcrypt=4.4.36=hd590300_1
  - libxkbcommon=1.13.2=hca5e8e5_0
  - libxml2=2.15.3=h49c6c72_0
  - libxml2-16=2.15.3=hca6bf5a_0
  - libzip=1.11.2=h6991a6a_0
  - libzlib=1.3.2=h25fd6f3_2
  - locket=1.0.0=pyhd8ed1ab_0
  - lz4-c=1.10.0=h5888daf_1
  - markupsafe=3.0.3=py312h8a5da7c_1
  - msgpack-python=1.2.1=py312h0a2e395_1
  - multidict=6.7.1=py312h8a5da7c_0
  - ncurses=6.6=hdb14827_0
  - netcdf4=1.7.4=nompi_py311hb115678_109
  - numcodecs=0.16.5=py312hf79963d_0
  - numpy=2.5.1=py312h33ff503_0
  - openssl=3.6.3=h35e630c_0
  - packaging=26.2=pyhc364b38_0
  - pango=1.56.4=hda50119_1
  - partd=1.4.2=pyhd8ed1ab_0
  - pcre2=10.47=haa7fec5_0
  - pip=26.1.2=pyh8b19718_0
  - pixman=0.46.4=h54a6638_2
  - propcache=0.5.2=py312h8a5da7c_0
  - psutil=7.2.2=py312h5253ce2_0
  - pthread-stubs=0.4=hb9d3cd8_1002
  - pyenchant=3.2.2=pyhd8ed1ab_0
  - pyfive=1.1.2=pyhd8ed1ab_0
  - pygments=2.20.0=pyhd8ed1ab_0
  - pysocks=1.7.1=pyha55dd90_7
  - python=3.12.13=hd63d673_0_cpython
  - python-dateutil=2.9.0.post0=pyhe01879c_2
  - python-gil=3.12.13=hd8ed1ab_0
  - python_abi=3.12=8_cp312
  - pyyaml=6.0.3=py312h8a5da7c_1
  - readline=8.3=h853b02a_0
  - requests=2.34.2=pyhcf101f3_0
  - roman-numerals=4.1.0=pyhd8ed1ab_0
  - s2n=1.7.5=h7e3ee7f_1
  - s3fs=2026.6.0=pyhd8ed1ab_0
  - scipy=1.18.0=py312h54fa4ab_0
  - setuptools=83.0.0=pyh332efcf_0
  - six=1.17.0=pyhe01879c_1
  - snappy=1.2.2=h03e3b7b_1
  - snowballstemmer=3.1.1=pyhd8ed1ab_0
  - sortedcontainers=2.4.0=pyhd8ed1ab_1
  - sphinx=9.1.0=pyhd8ed1ab_0
  - sphinx-copybutton=0.5.2=pyhd8ed1ab_1
  - sphinxcontrib-applehelp=2.0.0=pyhd8ed1ab_1
  - sphinxcontrib-devhelp=2.0.0=pyhd8ed1ab_1
  - sphinxcontrib-htmlhelp=2.1.0=pyhd8ed1ab_1
  - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_1
  - sphinxcontrib-qthelp=2.0.0=pyhd8ed1ab_1
  - sphinxcontrib-serializinghtml=2.0.0=pyhd8ed1ab_0
  - sphinxcontrib-spelling=8.0.2=pyhcf101f3_1
  - tblib=3.2.2=pyhcf101f3_0
  - tk=8.6.13=noxft_hd70dff1_3
  - toolz=1.1.0=pyhd8ed1ab_1
  - tornado=6.5.7=py312h4c3975b_0
  - typing_extensions=4.16.0=pyhcf101f3_0
  - tzdata=2026c=h151e31d_0
  - udunits2=2.2.28=h40f5838_3
  - uritools=6.1.2=pyhd8ed1ab_0
  - urllib3=2.7.0=pyhd8ed1ab_0
  - wayland=1.26.0=hd6090a7_0
  - wheel=0.47.0=pyhd8ed1ab_0
  - wrapt=2.2.2=py312h4c3975b_0
  - xkeyboard-config=2.48=h280c20c_0
  - xorg-libice=1.1.2=hb9d3cd8_0
  - xorg-libsm=1.2.6=he73a12e_0
  - xorg-libx11=1.8.13=he1eb515_0
  - xorg-libxau=1.0.12=hb03c661_1
  - xorg-libxcomposite=0.4.7=hb03c661_0
  - xorg-libxcursor=1.2.3=hb9d3cd8_0
  - xorg-libxdamage=1.1.6=hb9d3cd8_0
  - xorg-libxdmcp=1.1.5=hb03c661_1
  - xorg-libxext=1.3.7=hb03c661_0
  - xorg-libxfixes=6.0.2=hb03c661_0
  - xorg-libxi=1.8.3=hb03c661_0
  - xorg-libxinerama=1.1.6=hecca717_0
  - xorg-libxrandr=1.5.5=hb03c661_0
  - xorg-libxrender=0.9.12=hb9d3cd8_0
  - xorg-libxtst=1.2.5=hb9d3cd8_3
  - xorg-libxxf86vm=1.1.7=hb03c661_0
  - xorg-xorgproto=2025.1=hb03c661_0
  - yaml=0.2.5=h280c20c_3
  - yarl=1.24.5=py312h8a5da7c_0
  - zarr=3.2.1=pyhc364b38_0
  - zict=3.0.0=pyhd8ed1ab_1
  - zipp=4.1.0=pyhcf101f3_0
  - zstd=1.5.7=hb78ec9c_6
  - pip:
      - sphinx-toggleprompt==0.6.0
prefix: /home/slb93/miniconda3/envs/cf-docs

[sadielbartholomew]

All ready for review, thanks @davidhassell.

[davidhassell]

Hi Sadie - the method and execution all look good to me. Please merge when you're ready.

[sadielbartholomew]

CI job failures are unrelated but I will investigate - and also go in to update the job workflows which might be quite out of date in terms of versions for external sub-workflows referenced at this stage. Merging,