API reference: detect missing class pages & populate all gaps

docs/source/check_docs_api_coverage.py

@@ -1,4 +1,6 @@
-"""Check the method-coverage of all classes in docs/source/class.rst.
+"""Check the class-coverage and method-coverage of the API reference.
+
+All classes are extracted and checked for an entry in docs/source/class.rst
 
 All non-private methods of all such classes are checked for having an
 entry in their corresponding class's file in docs/source/class/
@@ -16,6 +18,7 @@
 
 """
 
+import inspect
 import os
 import re
 import sys
@@ -34,8 +37,10 @@
 if not source.endswith("source"):
     raise ValueError(f"Given directory {source} does not end with 'source'")
 
+n_undocumented_classes = 0
 n_undocumented_methods = 0
 n_missing_files = 0
+
 duplicate_method_entries = []
 
 for core in ("", "_core"):
@@ -50,20 +55,34 @@
         api_contents = f.read()
 
     class_names = [
-        i.split(".")[-1]
-        for i in api_contents.split("\n")
-        if package.__name__ + "." in i
+        name
+        for name, klass in inspect.getmembers(package, inspect.isclass)
+        if klass.__module__.startswith(package.__name__ + ".")
+        and not klass.__module__.startswith(package.__name__ + ".functions")
+        # This just counts top-level read-write i.e. cfdm.read and .write
+        and not klass.__module__.startswith(package.__name__ + ".read_write")
+        and name != "netcdf_indexer"  # lone function
     ]
 
     for class_name in class_names:
+        full_class_name = f"{package.__name__}.{class_name}"
+
+        if full_class_name not in api_contents:
+            print(
+                f"Class {full_class_name} not in docs/source/class{core}.rst"
+            )
+            n_missing_files += 1
+            n_undocumented_classes += 1
+            continue
+
         klass = getattr(package, class_name)
         methods = [
             method for method in dir(klass) if not method.startswith("_")
         ]
 
         class_name = ".".join([package.__name__, class_name])
 
-        rst_file = os.path.join(source, "class", class_name + ".rst")
+        rst_file = os.path.join(source, "class", full_class_name + ".rst")
 
         try:
             with open(rst_file) as f:
@@ -100,7 +119,7 @@
                         duplicate_method_entries.append(method)
         except FileNotFoundError:
             n_missing_files += 1
-            print(f"File {rst_file} does not exist")
+            print(f"File {rst_file} does not exist  for existing class")
 
 # Raise an exception to ensure a non-zero shell return code
 if n_undocumented_methods:
@@ -111,8 +130,9 @@
 
 if n_undocumented_methods or n_missing_files:
     raise ValueError(
-        f"Found undocumented methods ({n_undocumented_methods}) "
-        f"or missing .rst files ({n_missing_files})"
+        f"Found {n_undocumented_classes} undocumented classes, "
+        f"{n_undocumented_methods} undocumented methods and "
+        f"{n_missing_files} missing .rst files"
     )
 
 if duplicate_method_entries:

docs/source/class.rst

@@ -10,6 +10,8 @@
 
 Version |release| for version |version| of the CF conventions.
 
+.. note:: See also the :ref:`class_core`.
+
 
 Field construct class
 ---------------------
@@ -76,10 +78,29 @@ Data classes
    :toctree: class/
 
    cfdm.Data
+
+
+Array classes
+-------------
+
+Classes that support the creation and storage of arrays.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: class/
+
+   cfdm.Array
    cfdm.NetCDF4Array
    cfdm.H5netcdfArray
    cfdm.ZarrArray
-   cfdm.Array
+   cfdm.AggregatedArray
+   cfdm.FullArray
+   cfdm.NetCDFArray
+   cfdm.NumpyArray
+   cfdm.PyfiveArray
+   cfdm.ScipyNetcdfFileArray
+   cfdm.SparseArray
+
 
 Data compression classes
 ------------------------
@@ -94,11 +115,63 @@ Classes that support the creation and storage of compressed arrays.
    cfdm.Index
    cfdm.List
    cfdm.GatheredArray
+   cfdm.RaggedArray
+   cfdm.RaggedSubarray
    cfdm.RaggedContiguousArray
    cfdm.RaggedIndexedArray
    cfdm.RaggedIndexedContiguousArray
    cfdm.CompressedArray
    cfdm.Quantization
+   cfdm.BiLinearSubarray
+   cfdm.BiQuadraticLatitudeLongitudeSubarray
+   cfdm.GatheredSubarray
+   cfdm.InterpolationSubarray
+   cfdm.LinearSubarray
+   cfdm.QuadraticLatitudeLongitudeSubarray
+   cfdm.QuadraticSubarray
+   cfdm.Subarray
+   cfdm.SubsampledArray
+   cfdm.SubsampledSubarray
+
+UGRID related classes
+---------------------
+
+Classes that support the creation and storage of UGRID related arrays.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: class/
+
+   cfdm.BoundsFromNodesArray
+   cfdm.BoundsFromNodesSubarray
+   cfdm.CellConnectivityArray
+   cfdm.CellConnectivitySubarray
+   cfdm.PointTopologyArray
+
+Abstract base classes
+---------------------
+
+Abstract base classes that provide the basis for constructs and
+construct components.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: class/
+
+   cfdm.NodeCountProperties
+   cfdm.PartNodeCountProperties
+   cfdm.Container
+
+Implementation classes
+----------------------
+
+.. autosummary::
+   :nosignatures:
+   :toctree: class/
+
+   cfdm.Implementation
+   cfdm.CFDMImplementation
+
 
 Miscellaneous classes
 ---------------------
@@ -109,4 +182,6 @@ Miscellaneous classes
 
    cfdm.Constant
    cfdm.Configuration
-
+   cfdm.InterpolationParameter
+   cfdm.TiePointIndex
+   cfdm.Units

docs/source/class/cfdm.AggregatedArray.rst

@@ -0,0 +1,56 @@
+.. currentmodule:: cfdm
+.. default-role:: obj
+
+cfdm.AggregatedArray
+====================
+
+----
+
+.. autoclass:: cfdm.AggregatedArray
+   :no-members:
+   :no-inherited-members:
+
+Methods
+-------
+
+.. rubric:: Methods
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../method/
+   :template: method.rst
+
+   ~cfdm.AggregatedArray.Units
+   ~cfdm.AggregatedArray.array
+   ~cfdm.AggregatedArray.astype
+   ~cfdm.AggregatedArray.close
+   ~cfdm.AggregatedArray.copy
+   ~cfdm.AggregatedArray.dtype
+   ~cfdm.AggregatedArray.file_directory
+   ~cfdm.AggregatedArray.get_address
+   ~cfdm.AggregatedArray.get_attributes
+   ~cfdm.AggregatedArray.get_calendar
+   ~cfdm.AggregatedArray.get_compression_type
+   ~cfdm.AggregatedArray.get_filename
+   ~cfdm.AggregatedArray.get_fragment_array
+   ~cfdm.AggregatedArray.get_fragment_array_shape
+   ~cfdm.AggregatedArray.get_fragment_type
+   ~cfdm.AggregatedArray.get_fragmented_dimensions
+   ~cfdm.AggregatedArray.get_mask
+   ~cfdm.AggregatedArray.get_missing_values
+   ~cfdm.AggregatedArray.get_storage_options
+   ~cfdm.AggregatedArray.get_storage_protocol
+   ~cfdm.AggregatedArray.get_units
+   ~cfdm.AggregatedArray.get_unpack
+   ~cfdm.AggregatedArray.get_variable
+   ~cfdm.AggregatedArray.has_remote_storage_protocol
+   ~cfdm.AggregatedArray.ndim
+   ~cfdm.AggregatedArray.open
+   ~cfdm.AggregatedArray.replace_directory
+   ~cfdm.AggregatedArray.replace_filename
+   ~cfdm.AggregatedArray.shape
+   ~cfdm.AggregatedArray.size
+   ~cfdm.AggregatedArray.subarray_shapes
+   ~cfdm.AggregatedArray.subarrays
+   ~cfdm.AggregatedArray.to_dask_array
+   ~cfdm.AggregatedArray.to_memory

docs/source/class/cfdm.BiLinearSubarray.rst

@@ -0,0 +1,44 @@
+.. currentmodule:: cfdm
+.. default-role:: obj
+
+cfdm.BiLinearSubarray
+=====================
+
+----
+
+.. autoclass:: cfdm.BiLinearSubarray
+   :no-members:
+   :no-inherited-members:
+
+Methods
+-------
+
+.. rubric:: Methods
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../method/
+   :template: method.rst
+
+   ~cfdm.BiLinearSubarray.Units
+   ~cfdm.BiLinearSubarray.array
+   ~cfdm.BiLinearSubarray.astype
+   ~cfdm.BiLinearSubarray.bounds
+   ~cfdm.BiLinearSubarray.compressed_dimensions
+   ~cfdm.BiLinearSubarray.copy
+   ~cfdm.BiLinearSubarray.data
+   ~cfdm.BiLinearSubarray.dependent_tie_points
+   ~cfdm.BiLinearSubarray.dtype
+   ~cfdm.BiLinearSubarray.first
+   ~cfdm.BiLinearSubarray.get_attributes
+   ~cfdm.BiLinearSubarray.get_calendar
+   ~cfdm.BiLinearSubarray.get_compression_type
+   ~cfdm.BiLinearSubarray.get_filename
+   ~cfdm.BiLinearSubarray.get_interpolation_description
+   ~cfdm.BiLinearSubarray.get_units
+   ~cfdm.BiLinearSubarray.indices
+   ~cfdm.BiLinearSubarray.ndim
+   ~cfdm.BiLinearSubarray.parameters
+   ~cfdm.BiLinearSubarray.shape
+   ~cfdm.BiLinearSubarray.size
+   ~cfdm.BiLinearSubarray.subarea_indices

docs/source/class/cfdm.BiQuadraticLatitudeLongitudeSubarray.rst

@@ -0,0 +1,44 @@
+.. currentmodule:: cfdm
+.. default-role:: obj
+
+cfdm.BiQuadraticLatitudeLongitudeSubarray
+=========================================
+
+----
+
+.. autoclass:: cfdm.BiQuadraticLatitudeLongitudeSubarray
+   :no-members:
+   :no-inherited-members:
+
+Methods
+-------
+
+.. rubric:: Methods
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../method/
+   :template: method.rst
+
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.Units
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.array
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.astype
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.bounds
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.compressed_dimensions
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.copy
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.data
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.dependent_tie_points
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.dtype
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.first
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.get_attributes
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.get_calendar
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.get_compression_type
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.get_filename
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.get_interpolation_description
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.get_units
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.indices
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.ndim
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.parameters
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.shape
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.size
+   ~cfdm.BiQuadraticLatitudeLongitudeSubarray.subarea_indices

docs/source/class/cfdm.BoundsFromNodesArray.rst

@@ -0,0 +1,50 @@
+.. currentmodule:: cfdm
+.. default-role:: obj
+
+cfdm.BoundsFromNodesArray
+=========================
+
+----
+
+.. autoclass:: cfdm.BoundsFromNodesArray
+   :no-members:
+   :no-inherited-members:
+
+Methods
+-------
+
+.. rubric:: Methods
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../method/
+   :template: method.rst
+
+   ~cfdm.BoundsFromNodesArray.Units
+   ~cfdm.BoundsFromNodesArray.array
+   ~cfdm.BoundsFromNodesArray.astype
+   ~cfdm.BoundsFromNodesArray.compressed_array
+   ~cfdm.BoundsFromNodesArray.compressed_dimensions
+   ~cfdm.BoundsFromNodesArray.conformed_data
+   ~cfdm.BoundsFromNodesArray.copy
+   ~cfdm.BoundsFromNodesArray.dtype
+   ~cfdm.BoundsFromNodesArray.get_Subarray
+   ~cfdm.BoundsFromNodesArray.get_attributes
+   ~cfdm.BoundsFromNodesArray.get_calendar
+   ~cfdm.BoundsFromNodesArray.get_cell_dimension
+   ~cfdm.BoundsFromNodesArray.get_compressed_axes
+   ~cfdm.BoundsFromNodesArray.get_compressed_dimension
+   ~cfdm.BoundsFromNodesArray.get_compression_type
+   ~cfdm.BoundsFromNodesArray.get_filename
+   ~cfdm.BoundsFromNodesArray.get_node_coordinates
+   ~cfdm.BoundsFromNodesArray.get_start_index
+   ~cfdm.BoundsFromNodesArray.get_units
+   ~cfdm.BoundsFromNodesArray.ndim
+   ~cfdm.BoundsFromNodesArray.shape
+   ~cfdm.BoundsFromNodesArray.size
+   ~cfdm.BoundsFromNodesArray.source
+   ~cfdm.BoundsFromNodesArray.subarray_parameters
+   ~cfdm.BoundsFromNodesArray.subarray_shapes
+   ~cfdm.BoundsFromNodesArray.subarrays
+   ~cfdm.BoundsFromNodesArray.to_dask_array
+   ~cfdm.BoundsFromNodesArray.to_memory