Merge pull request NCAS-CMS#277 from sadielbartholomew/find-api-ref-d…

…uplicate-entries Detection of duplicates in API reference, some to remove
davidhassell · Nov 14, 2023 · 28fb90c · 28fb90c
2 parents 247a19a + 3619d87
commit 28fb90c
Showing 10 changed files with 63 additions and 89 deletions.
diff --git a/docs/source/check_docs_api_coverage.py b/docs/source/check_docs_api_coverage.py
@@ -16,6 +16,7 @@
 
 """
 import os
+import re
 import sys
 
 import cfdm as package
@@ -34,6 +35,7 @@
 
 n_undocumented_methods = 0
 n_missing_files = 0
+duplicate_method_entries = []
 
 for core in ("", "_core"):
     if core:
@@ -68,12 +70,33 @@
 
             for method in methods:
                 method = ".".join([class_name, method])
-                if method not in rst_contents:
+                count = rst_contents.count(method)
+                if count == 0:
                     n_undocumented_methods += 1
                     print(
                         f"Method {method} not in "
                         f"{os.path.join(source, 'class', rst_file)}"
                     )
+                elif count > 1:
+                    # The method appears more than once, but may be a
+                    # sub-string of another method name, e.g. this gets caught:
+                    #     [cfdm.List.]nc_set_variable
+                    # due to the presence of this method:
+                    #     [cfdm.List.]nc_set_variable_groups
+                    # so we must account for that. Checking next character
+                    # of duplicate(s) is something other than a newline or
+                    # whitespace, seems robust and simplest.
+                    end_loc = [
+                        m.end(0) for m in re.finditer(method, rst_contents)
+                    ]
+                    chars = [rst_contents[c] for c in [e for e in end_loc]]
+
+                    # Any character that isn't a newline or whitespace
+                    # indicates another method which the method is a substring
+                    # of and can be excluded. If there are still duplicates,
+                    # we have genuine duplicate listing entries to report.
+                    if chars.count("\n") + chars.count(" ") > 1:
+                        duplicate_method_entries.append(method)
         except FileNotFoundError:
             n_missing_files += 1
             print(f"File {rst_file} does not exist")
@@ -91,4 +114,13 @@
         f"or missing .rst files ({n_missing_files})"
     )
 
+if duplicate_method_entries:
+    duplicate_method_entries.sort()
+    entries = "\n".join(duplicate_method_entries)  # can't set \n in f-string!
+    print(
+        "WARNING: some methods are listed multiple times inside one class "
+        "file/page. Decide if the duplicates are intended and if not remove "
+        f"them. They are:\n{entries}\n"
+    )
+
 print("All non-private methods are documented")
diff --git a/docs/source/class/cfdm.Data.rst b/docs/source/class/cfdm.Data.rst
@@ -36,11 +36,30 @@ Units
    ~cfdm.Data.get_units
    ~cfdm.Data.has_units
    ~cfdm.Data.set_units
+
+Date-time support
+-----------------
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../method/
+   :template: method.rst
+
    ~cfdm.Data.del_calendar
    ~cfdm.Data.get_calendar
    ~cfdm.Data.has_calendar
    ~cfdm.Data.set_calendar
 
+.. rubric:: Attributes
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../attribute/
+   :template: attribute.rst
+
+   ~cfdm.Data.datetime_array
+   ~cfdm.Data.datetime_as_string
+
 Data creation routines
 ----------------------
 
@@ -106,29 +125,6 @@ Adding and removing elements
    :template: method.rst
 
    ~cfdm.Data.unique
-
-Date-time support
------------------
-
-.. autosummary::
-   :nosignatures:
-   :toctree: ../method/
-   :template: method.rst
-
-   ~cfdm.Data.del_calendar
-   ~cfdm.Data.get_calendar
-   ~cfdm.Data.has_calendar
-   ~cfdm.Data.set_calendar
-
-.. rubric:: Attributes
-
-.. autosummary::
-   :nosignatures:
-   :toctree: ../attribute/
-   :template: attribute.rst
-
-   ~cfdm.Data.datetime_array
-   ~cfdm.Data.datetime_as_string
 
 Indexing routines
 -----------------

diff --git a/docs/source/class/cfdm.Domain.rst b/docs/source/class/cfdm.Domain.rst
@@ -114,7 +114,6 @@ Miscellaneous
    :template: method.rst
 
    ~cfdm.Domain.apply_masking
-   ~cfdm.Domain.climatological_time_axes
    ~cfdm.Domain.copy
    ~cfdm.Domain.creation_commands
    ~cfdm.Domain.equals
@@ -123,7 +122,6 @@ Miscellaneous
    ~cfdm.Domain.has_bounds
    ~cfdm.Domain.has_data
    ~cfdm.Domain.has_geometry
-   ~cfdm.Domain.apply_masking   
    ~cfdm.Domain.get_original_filenames
    ~cfdm.Domain.uncompress
 

diff --git a/docs/source/class/cfdm.Field.rst b/docs/source/class/cfdm.Field.rst
@@ -117,10 +117,6 @@ Metadata constructs
    ~cfdm.Field.get_construct
    ~cfdm.Field.has_construct
    ~cfdm.Field.set_construct
-   ~cfdm.Field.del_data_axes
-   ~cfdm.Field.get_data_axes
-   ~cfdm.Field.has_data_axes
-   ~cfdm.Field.set_data_axes
    ~cfdm.Field.domain_axis_key
    ~cfdm.Field.auxiliary_coordinate
    ~cfdm.Field.auxiliary_coordinates
@@ -187,7 +183,6 @@ Miscellaneous
    :toctree: ../method/
    :template: method.rst
 
-   ~cfdm.Field.climatological_time_axes
    ~cfdm.Field.compress
    ~cfdm.Field.copy
    ~cfdm.Field.creation_commands

diff --git a/docs/source/class/cfdm.NetCDFArray.rst b/docs/source/class/cfdm.NetCDFArray.rst
@@ -70,7 +70,6 @@ File
    ~cfdm.NetCDFArray.get_formats
    ~cfdm.NetCDFArray.get_groups
    ~cfdm.NetCDFArray.get_mask
-   ~cfdm.NetCDFArray.get_address
 
 Miscellaneous
 -------------

diff --git a/docs/source/class/cfdm.core.Coordinate.rst b/docs/source/class/cfdm.core.Coordinate.rst
@@ -119,21 +119,6 @@ Climatology
    ~cfdm.core.Coordinate.get_climatology
    ~cfdm.core.Coordinate.is_climatology
    ~cfdm.core.Coordinate.set_climatology
-
-Modification
-------------
-
-.. rubric:: Methods
-
-.. autosummary::
-   :nosignatures:
-   :toctree: ../method/
-   :template: method.rst
-
-   ~cfdm.core.Coordinate.del_data
-   ~cfdm.core.Coordinate.set_data
-   ~cfdm.core.Coordinate.del_bounds
-   ~cfdm.core.Coordinate.set_bounds
 
 Miscellaneous
 -------------

diff --git a/docs/source/class/cfdm.core.Data.rst b/docs/source/class/cfdm.core.Data.rst
@@ -36,6 +36,15 @@ Units
    ~cfdm.core.Data.get_units
    ~cfdm.core.Data.has_units
    ~cfdm.core.Data.set_units
+
+Date-time support
+-----------------
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../method/
+   :template: method.rst
+
    ~cfdm.core.Data.del_calendar
    ~cfdm.core.Data.get_calendar
    ~cfdm.core.Data.has_calendar
@@ -54,19 +63,6 @@ From existing data
 
    ~cfdm.core.Data.copy
 
-Date-time support
------------------
-
-.. autosummary::
-   :nosignatures:
-   :toctree: ../method/
-   :template: method.rst
-
-   ~cfdm.core.Data.del_calendar
-   ~cfdm.core.Data.get_calendar
-   ~cfdm.core.Data.has_calendar
-   ~cfdm.core.Data.set_calendar
-
 Mask support
 ------------
 

diff --git a/docs/source/class/cfdm.core.DomainAxis.rst b/docs/source/class/cfdm.core.DomainAxis.rst
@@ -37,15 +37,6 @@ Size
    ~cfdm.core.DomainAxis.has_size
    ~cfdm.core.DomainAxis.set_size
 
-.. rubric:: Attributes
-
-.. autosummary::
-   :nosignatures:
-   :toctree: ../attribute/
-   :template: attribute.rst
-
-   ~cfdm.core.DomainAxis.construct_type
-
 Miscellaneous
 -------------
 

diff --git a/docs/source/class/cfdm.core.Field.rst b/docs/source/class/cfdm.core.Field.rst
@@ -91,10 +91,6 @@ Metadata constructs
    ~cfdm.core.Field.get_construct
    ~cfdm.core.Field.has_construct
    ~cfdm.core.Field.set_construct
-   ~cfdm.core.Field.del_data_axes
-   ~cfdm.core.Field.get_data_axes
-   ~cfdm.core.Field.has_data_axes
-   ~cfdm.core.Field.set_data_axes
 
 .. rubric:: Attributes
 

diff --git a/docs/source/class/cfdm.core.PropertiesDataBounds.rst b/docs/source/class/cfdm.core.PropertiesDataBounds.rst
@@ -77,7 +77,8 @@ Bounds
    :template: attribute.rst
 
    ~cfdm.core.PropertiesDataBounds.bounds
-   Geometries
+
+Geometries
 ^^^^^^^^^^
 
 .. rubric:: Methods
@@ -104,21 +105,6 @@ Bounds
    :template: attribute.rst
 
    ~cfdm.core.PropertiesDataBounds.interior_ring
-
-Modification
-------------
-
-.. rubric:: Methods
-
-.. autosummary::
-   :nosignatures:
-   :toctree: ../method/
-   :template: method.rst
-
-   ~cfdm.core.PropertiesDataBounds.del_data
-   ~cfdm.core.PropertiesDataBounds.set_data
-   ~cfdm.core.PropertiesDataBounds.del_bounds
-   ~cfdm.core.PropertiesDataBounds.set_bounds
 
 Miscellaneous
 -------------