Merge pull request #559 from larrybradley/numpydoc

Add numpydoc validator to pre-commit

.pre-commit-config.yaml

@@ -57,8 +57,7 @@ repos:
     rev: "v0.4.7"
     hooks:
       - id: ruff
-      # args: ["--fix", "--show-fixes"]
-        args: ["--show-fixes"]
+        args: ["--fix", "--show-fixes"]
 
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.17.0
@@ -102,6 +101,11 @@ repos:
         additional_dependencies:
           - tomli
 
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0rc2
+    hooks:
+      - id: numpydoc-validation
+
   - repo: https://github.com/PyCQA/docformatter
     rev: v1.7.5
     hooks:

dev/regions_parse.py

@@ -16,7 +16,7 @@
 @click.group()
 def cli():
     """
-    astropy.regions parser debugging tool.
+    Region parser debugging tool.
     """
     pass
 

pyproject.toml

@@ -192,6 +192,28 @@ exclude_dirs = ['*/tests/test_casa_mask.py']
 [tool.bandit.assert_used]
 skips = ['*_test.py', '*/test_*.py', '*/tests/helpers.py']
 
+[tool.numpydoc_validation]
+checks = [
+    'all',   # report on all checks, except the below
+    'ES01',  # missing extended summary
+    'EX01',  # missing "Examples"
+    'GL08',  # missing docstring
+    'SA01',  # missing "See Also"
+    'SA04',  # missing "See Also" description
+    'RT02',  # only type in "Returns" section (no name)
+    'SS06',  # single-line summary
+    'RT01',  # do not require return type for lazy properties
+]
+
+# don't report on objects that match any of these regex;
+# remember to use single quotes for regex in TOML
+exclude = [
+    '\._.*',  # private functions/methods
+    '^test_*',  # test code
+    '^conftest.*$',  # pytest configuration
+    '^helpers.*$',  # helper modules
+]
+
 [tool.docformatter]
     wrap-summaries = 72
     pre-summary-newline = true

regions/_utils/examples.py

@@ -67,6 +67,11 @@ def make_example_dataset(data='simulated', config=None):
 class ExampleDataset:
     """
     Base class for an example dataset.
+
+    Parameters
+    ----------
+    config : dict or None
+        Configuration options.
     """
 
     def __init__(self, config=None):

regions/core/attributes.py

@@ -157,6 +157,14 @@ def _validate(self, value):
 class RegionType(RegionAttribute):
     """
     Descriptor class to check the region type of value.
+
+    Parameters
+    ----------
+    name : str
+        The name of the attribute.
+
+    regionclass : `~regions.Region`
+        The region class to check.
     """
 
     def __init__(self, name, regionclass):

regions/core/core.py

@@ -23,6 +23,11 @@ class Region(abc.ABC):
     def copy(self, **changes):
         """
         Make an independent (deep) copy.
+
+        Parameters
+        ----------
+        **changes : dict
+            Changes to make to the region parameters.
         """
         fields = list(self._params) + ['meta', 'visual']
 
@@ -97,6 +102,11 @@ def __eq__(self, other):
     def __ne__(self, other):
         """
         Inequality operator for Region.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region that will be compared.
         """
         return not (self == other)
 
@@ -105,6 +115,11 @@ def intersection(self, other):
         """
         Return a region representing the intersection of this region
         with ``other``.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the intersection.
         """
         raise NotImplementedError
 
@@ -113,6 +128,11 @@ def symmetric_difference(self, other):
         """
         Return the union of the two regions minus any areas contained in
         the intersection of the two regions.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the symmetric difference.
         """
         raise NotImplementedError
 
@@ -121,6 +141,11 @@ def union(self, other):
         """
         Return a region representing the union of this region with
         ``other``.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the union.
         """
         raise NotImplementedError
 
@@ -218,6 +243,11 @@ def intersection(self, other):
         """
         Return a region representing the intersection of this region
         with ``other``.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the intersection.
         """
         from regions.core.compound import CompoundPixelRegion
         return CompoundPixelRegion(region1=self, region2=other,
@@ -227,6 +257,11 @@ def symmetric_difference(self, other):
         """
         Return the union of the two regions minus any areas contained in
         the intersection of the two regions.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the symmetric difference.
         """
         from regions.core.compound import CompoundPixelRegion
         return CompoundPixelRegion(region1=self, region2=other,
@@ -236,6 +271,11 @@ def union(self, other):
         """
         Return a region representing the union of this region with
         ``other``.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the union.
         """
         from regions.core.compound import CompoundPixelRegion
         return CompoundPixelRegion(region1=self, region2=other,
@@ -418,6 +458,11 @@ def intersection(self, other):
         """
         Return a region representing the intersection of this region
         with ``other``.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the intersection.
         """
         from regions.core.compound import CompoundSkyRegion
         return CompoundSkyRegion(region1=self, region2=other,
@@ -427,6 +472,11 @@ def symmetric_difference(self, other):
         """
         Return the union of the two regions minus any areas contained in
         the intersection of the two regions.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the symmetric difference.
         """
         from regions.core.compound import CompoundSkyRegion
         return CompoundSkyRegion(region1=self, region2=other,
@@ -436,6 +486,11 @@ def union(self, other):
         """
         Return a region representing the union of this region with
         ``other``.
+
+        Parameters
+        ----------
+        other : `Region`
+            The other region to use for the union.
         """
         from regions.core.compound import CompoundSkyRegion
         return CompoundSkyRegion(region1=self, region2=other,

regions/core/metadata.py

@@ -10,6 +10,14 @@
 class Meta(dict):
     """
     A base class for region metadata.
+
+    Parameters
+    ----------
+    seq : dict-like, optional
+        A dictionary or other mapping object to initialize the metadata.
+
+    **kwargs
+        Additional keyword arguments to initialize the metadata.
     """
 
     valid_keys = []

regions/core/regions.py

@@ -115,6 +115,7 @@ def pop(self, index=-1):
         Returns
         -------
         result : `~regions.Region`
+            The removed region.
         """
         return self.regions.pop(index)
 

regions/core/registry.py

@@ -64,6 +64,26 @@ def identify_format(cls, filename, classobj, methodname):
     def read(cls, filename, classobj, format=None, **kwargs):
         """
         Read in a regions file.
+
+        Parameters
+        ----------
+        filename : str
+            The file to read from.
+
+        classobj : class
+            The class to read the regions into.
+
+        format : str, optional
+            The format of the file. If not provided, the format will be
+            identified based on the file name or contents.
+
+        **kwargs : dict, optional
+            Additional keyword arguments to pass to the reader.
+
+        Returns
+        -------
+        regions : classobj
+            The regions object read from the file.
         """
         if format is None:
             format = cls.identify_format(filename, classobj, 'read')
@@ -83,6 +103,26 @@ def read(cls, filename, classobj, format=None, **kwargs):
     def parse(cls, data, classobj, format=None, **kwargs):
         """
         Parse a regions string or table.
+
+        Parameters
+        ----------
+        data : str, Table
+            The data to parse.
+
+        classobj : class
+            The class to parse the regions into.
+
+        format : str, optional
+            The format of the data. If not provided, an error will be
+            raised.
+
+        **kwargs : dict, optional
+            Additional keyword arguments to pass to the parser.
+
+        Returns
+        -------
+        regions : classobj
+            The regions object parsed from the data.
         """
         if format is None:
             cls._no_format_error(classobj)
@@ -102,6 +142,24 @@ def parse(cls, data, classobj, format=None, **kwargs):
     def write(cls, regions, filename, classobj, format=None, **kwargs):
         """
         Write to a regions file.
+
+        Parameters
+        ----------
+        regions : classobj
+            The regions object to write.
+
+        filename : str
+            The file to write to.
+
+        classobj : class
+            The class of the regions object.
+
+        format : str, optional
+            The format of the file. If not provided, an error will be
+            raised.
+
+        **kwargs : dict, optional
+            Additional keyword arguments to pass to the writer.
         """
         if format is None:
             format = cls.identify_format(filename, classobj, 'write')
@@ -121,6 +179,26 @@ def write(cls, regions, filename, classobj, format=None, **kwargs):
     def serialize(cls, regions, classobj, format=None, **kwargs):
         """
         Serialize to a regions string or table.
+
+        Parameters
+        ----------
+        regions : classobj
+            The regions object to serialize.
+
+        classobj : class
+            The class of the regions object.
+
+        format : str, optional
+            The format of the data. If not provided, an error will be
+            raised.
+
+        **kwargs : dict, optional
+            Additional keyword arguments to pass to the serializer.
+
+        Returns
+        -------
+        data : str, Table
+            The data serialized from the regions object.
         """
         if format is None:
             cls._no_format_error(classobj)
@@ -140,6 +218,16 @@ def serialize(cls, regions, classobj, format=None, **kwargs):
     def get_formats(cls, classobj):
         """
         Get the registered I/O formats as a Table.
+
+        Parameters
+        ----------
+        classobj : class
+            The class to get the formats for.
+
+        Returns
+        -------
+        tbl : Table
+            The table of formats.
         """
         filetypes = list({key[2] for key in cls.registry
                           if key[0] == classobj})