Add numpydoc pre-commit. (#3677)

* Follow numpydoc convention.

* Follow numpydoc convention.

* Fix doc.

Author: MaxJPRey

.pre-commit-config.yaml

@@ -63,6 +63,12 @@ repos:
   -   id: blacken-docs
       additional_dependencies: [black==23.9.1]
 
+
+# - repo: https://github.com/numpy/numpydoc
+#   rev: v1.6.0
+#   hooks:
+#     - id: numpydoc-validation
+
 # - repo: https://github.com/pycqa/pydocstyle
 #   rev: 6.1.1
 #   hooks:

doc/source/conf.py

@@ -158,15 +158,15 @@ def setup(app):
     "GL10",  # reST directives {directives} must be followed by two colons
     # Return
     "RT04", # Return value description should start with a capital letter"
-    "RT05", # Return value description should finish with "."'
+    "RT05", # Return value description should finish with "."
     # Summary
     "SS01",  # No summary found
     "SS02",  # Summary does not start with a capital letter
     "SS03",  # Summary does not end with a period
     "SS04",  # Summary contains heading whitespaces
     "SS05",  # Summary must start with infinitive verb, not third person
     # Parameters
-    "PR10",  # Parameter "{param_name}" requires a space before the colon '
+    "PR10",  # Parameter "{param_name}" requires a space before the colon
     # separating the parameter name and type",
 }
 

pyaedt/application/Variables.py

@@ -263,7 +263,7 @@ def decompose_variable_value(variable_value, full_variables={}):
     Returns
     -------
     tuples
-        tuples made of the float value of the variable and the units exposed as a string.
+        Tuples made of the float value of the variable and the units exposed as a string.
     """
     # set default return values - then check for valid units
     float_value = variable_value
@@ -323,7 +323,7 @@ def generate_validation_errors(property_names, expected_settings, actual_setting
         List of property names.
     expected_settings : List[str]
         List of the expected settings.
-    actual_settings: List[str]
+    actual_settings : List[str]
         List of actual settings.
 
     Returns
@@ -1761,7 +1761,7 @@ def __mul__(self, other):
         """Multiply the variable with a number or another variable and return a new object.
 
                 Parameters
-                ---------
+                ----------
                 other : numbers.Number or variable
                     Object to be multiplied.
 
@@ -1820,7 +1820,7 @@ def __add__(self, other):
         """Add the variable to another variable to return a new object.
 
         Parameters
-        ---------
+        ----------
         other : class:`pyaedt.application.Variables.Variable`
             Object to be multiplied.
 
@@ -1861,7 +1861,7 @@ def __sub__(self, other):
         """Subtract another variable from the variable to return a new object.
 
         Parameters
-        ---------
+        ----------
         other : class:`pyaedt.application.Variables.Variable`
             Object to be subtracted.
 
@@ -1904,7 +1904,7 @@ def __truediv__(self, other):
         """Divide the variable by a number or another variable to return a new object.
 
         Parameters
-        ---------
+        ----------
         other : numbers.Number or variable
             Object by which to divide.
 
@@ -1948,7 +1948,7 @@ def __rtruediv__(self, other):
         """Divide another object by this object.
 
         Parameters
-        ---------
+        ----------
         other : numbers.Number or variable
             Object to divide by.
 

pyaedt/emit_core/results/revision.py

@@ -79,7 +79,7 @@ def _load_revision(self):
         Load this revision.
 
         Examples
-        ----------
+        --------
         >>> aedtapp.results.revision.load_revision()
         """
         if self.revision_loaded:
@@ -105,7 +105,7 @@ def result_mode_error():
     @pyaedt_function_handler()
     def get_interaction(self, domain):
         """
-        Creates a new interaction for a domain.
+        Create a new interaction for a domain.
 
         Parameters
         ----------
@@ -118,7 +118,7 @@ def get_interaction(self, domain):
             Interaction object.
 
         Examples
-        ----------
+        --------
         >>> domain = aedtapp.results.interaction_domain()
         >>> rev.get_interaction(domain)
 
@@ -146,7 +146,7 @@ def run(self, domain):
             Interaction object.
 
         Examples
-        ----------
+        --------
         >>> domain = aedtapp.results.interaction_domain()
         >>> rev.run(domain)
 
@@ -180,7 +180,7 @@ def is_domain_valid(self, domain):
             ``InteractionDomain`` object for constraining the analysis parameters.
 
         Examples
-        ----------
+        --------
         >>> domain = aedtapp.interaction_domain()
         >>> aedtapp.results.current_revision.is_domain_valid(domain)
         True
@@ -200,12 +200,12 @@ def get_instance_count(self, domain):
             ``InteractionDomain`` object for constraining the analysis parameters.
 
         Returns
-        --------
+        -------
         count : int
             Number of instances in the domain for the current revision.
 
         Examples
-        ----------
+        --------
         >>> domain = aedtapp.interaction_domain()
         >>> num_instances = aedtapp.results.current_revision.get_instance_count(domain)
         """
@@ -228,7 +228,7 @@ def get_receiver_names(self):
             List of receiver names.
 
         Examples
-        ----------
+        --------
         >>> rxs = aedtapp.results.current_revision.get_reciver_names()
         """
         if self.revision_loaded:
@@ -262,7 +262,7 @@ def get_interferer_names(self, interferer_type=None):
             List of interfering systems' names.
 
         Examples
-        ----------
+        --------
         >>> transmitters = aedtapp.results.current_revision.get_interferer_names(InterfererType.TRANSMITTERS)
         >>> emitters = aedtapp.results.current_revision.get_interferer_names(InterfererType.EMITTERS)
         >>> both = aedtapp.results.current_revision.get_interferer_names(InterfererType.TRANSMITTERS_AND_EMITTERS)
@@ -301,7 +301,7 @@ def get_band_names(self, radio_name, tx_rx_mode=None):
             List of ``tx`` or ``rx`` band/waveform names.
 
         Examples
-        ----------
+        --------
         >>> bands = aedtapp.results.current_revision.get_band_names('Bluetooth', TxRxMode.RX)
         >>> waveforms = aedtapp.results.current_revision.get_band_names('USB_3.x', TxRxMode.TX)
         """
@@ -340,7 +340,7 @@ def get_active_frequencies(self, radio_name, band_name, tx_rx_mode, units=""):
             List of ``tx`` or ``rx`` radio/emitter frequencies.
 
         Examples
-        ----------
+        --------
         >>> freqs = aedtapp.results.current_revision.get_active_frequencies(
                 'Bluetooth', 'Rx - Base Data Rate', TxRxMode.RX)
         """
@@ -361,7 +361,7 @@ def notes(self):
         Add notes to the revision.
 
         Examples
-        ----------
+        --------
         >>> aedtapp.results.current_revision.notes = "Added a filter to the WiFi Radio."
         >>> aedtapp.results.current_revision.notes
         'Added a filter to the WiFi Radio.'
@@ -383,7 +383,7 @@ def n_to_1_limit(self):
         - A value of  ``-1`` allows unlimited N to 1. (N is set to the maximum.)
 
         Examples
-        ----------
+        --------
         >>> aedtapp.results.current_revision.n_to_1_limit = 2**20
         >>> aedtapp.results.current_revision.n_to_1_limit
         1048576

pyaedt/hfss.py

@@ -321,7 +321,7 @@ def _create_boundary(self, name, props, boundary_type):
         """Create a boundary.
 
         Parameters
-        ---------
+        ----------
         name : str
             Name of the boundary.
         props : list

pyaedt/maxwell.py

@@ -2261,7 +2261,7 @@ def _create_boundary(self, name, props, boundary_type):
         """Create a boundary.
 
         Parameters
-        ---------
+        ----------
         name : str
             Name of the boundary.
         props : list

pyaedt/modeler/modeler3d.py

@@ -1390,7 +1390,7 @@ def change_region_padding(self, padding_data, padding_type, direction=None, regi
             ``True`` if successful, else ``None``.
 
         Examples
-        ----------
+        --------
         >>> import pyaedt
         >>> app = pyaedt.Icepak()
         >>> app.modeler.change_region_padding("10mm", padding_type="Absolute Offset", direction="-X")
@@ -1474,7 +1474,7 @@ def change_region_coordinate_system(self, region_cs="Global", region_name="Regio
             ``True`` if successful, else ``None``.
 
         Examples
-        ----------
+        --------
         >>> import pyaedt
         >>> app = pyaedt.Icepak()
         >>> app.modeler.create_coordinate_system(origin=[1, 1, 1], name="NewCS")

pyaedt/modules/Boundary.py

@@ -225,7 +225,7 @@ def targetcs(self):
         Returns
         -------
         str
-            Native Component Coordinate System
+            Native Component Coordinate System.
         """
         if "TargetCS" in list(self.props.keys()):
             return self.props["TargetCS"]
@@ -3690,7 +3690,7 @@ def auto_update(self, b):
 
         Parameters
         ----------
-        b: bool
+        b : bool
             Whether to enable auto-update.
 
         """
@@ -3848,7 +3848,7 @@ def name(self, new_network_name):
 
         Parameters
         ----------
-        new_network_name: str
+        new_network_name : str
             New name of the network.
         """
         bound_names = [b.name for b in self._app.boundaries]
@@ -3929,11 +3929,11 @@ def add_boundary_node(self, name, assignment_type, value):
 
         Parameters
         ----------
-        name: str
+        name : str
             Name of the node.
-        assignment_type: str
+        assignment_type : str
             Type assignment. Options are ``"Power"`` and ``"Temperature"``.
-        value: str or float or dict
+        value : str or float or dict
             String, float, or dictionary containing the value of the assignment.
             If a float is passed the ``"W"`` or ``"cel"`` unit is used, depending on
             the selection for the ``assignment_type`` parameter. If ``"Power"`
@@ -3943,7 +3943,7 @@ def add_boundary_node(self, name, assignment_type, value):
         Returns
         -------
         bool
-            True if successful.
+            ``True`` if successful.
 
         Examples
         --------
@@ -4082,7 +4082,7 @@ def add_nodes_from_dictionaries(self, nodes_dict):
         Add nodes to the network from dictionary.
 
         Parameters
-        -------
+        ----------
         nodes_dict : list or dict
             A dictionary or list of dictionaries containing nodes to add to the network. Different
             node types require different key and value pairs:
@@ -4431,8 +4431,8 @@ def props(self, props):
             Set properties of the node.
 
             Parameters
-            -------
-            props: dict
+            ----------
+            props : dict
                 Node properties.
             """
             self._props = props

pyproject.toml

@@ -180,4 +180,29 @@ testpaths = [
     "_unittest",
 ]
 
-
+[tool.numpydoc_validation]
+checks = [
+    "GL06",  # Found unknown section
+    "GL07",  # Sections are in the wrong order.
+    "GL08",  # The object does not have a docstring
+    "GL09",  # Deprecation warning should precede extended summary
+    "GL10",  # reST directives {directives} must be followed by two colons
+    # Return
+    "RT04", # Return value description should start with a capital letter"
+    "RT05", # Return value description should finish with "."
+    # Summary
+    "SS01",  # No summary found
+    "SS02",  # Summary does not start with a capital letter
+    "SS03",  # Summary does not end with a period
+    "SS04",  # Summary contains heading whitespaces
+    "SS05",  # Summary must start with infinitive verb, not third person
+    # Parameters
+    "PR10",  # Parameter "{param_name}" requires a space before the colon
+    # separating the parameter name and type",
+]
+exclude = [
+    '\.AEDTMessageManager.add_message$',  # bad SS05
+    '\.Modeler3D\.create_choke$',  # bad RT05
+    '\._unittest\',  # missing docstring for tests
+    'HistoryProps.',  # bad RT05 because of the base class named OrderedDict
+]