From 7127ddad0d26ccf5d571691fb4cd07a79a2119d4 Mon Sep 17 00:00:00 2001 From: Maxime Rey Date: Fri, 29 Sep 2023 17:04:48 +0200 Subject: [PATCH 1/3] Follow numpydoc convention. --- .pre-commit-config.yaml | 8 +++++++- doc/source/conf.py | 4 ++-- pyproject.toml | 26 +++++++++++++++++++++++++- 3 files changed, 34 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 148db396a9a..03beff67832 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -53,7 +53,7 @@ repos: # validate GitHub workflow files - repo: https://github.com/python-jsonschema/check-jsonschema - rev: 0.26.3 + rev: 0.27.0 hooks: - id: check-github-workflows @@ -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: diff --git a/doc/source/conf.py b/doc/source/conf.py index 8d1087d7a8e..69689ab97ff 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -144,7 +144,7 @@ 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 @@ -152,7 +152,7 @@ def setup(app): "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", } diff --git a/pyproject.toml b/pyproject.toml index 10998debf72..acbc61b5370 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -176,4 +176,28 @@ 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 + 'HistoryProps.', # bad RT05 because of the base class named OrderedDict +] From a18b49089f541a1ff6dfd7f7966e92d11ef97252 Mon Sep 17 00:00:00 2001 From: Maxime Rey Date: Fri, 29 Sep 2023 17:06:55 +0200 Subject: [PATCH 2/3] Follow numpydoc convention. --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index acbc61b5370..780943fc447 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -199,5 +199,6 @@ checks = [ 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 ] From fec6bf2a1037450d06c3c6a2612e1416f471bc7e Mon Sep 17 00:00:00 2001 From: Maxime Rey Date: Thu, 5 Oct 2023 20:47:07 +0200 Subject: [PATCH 3/3] Fix doc. --- .pre-commit-config.yaml | 8 ++++---- pyaedt/application/Variables.py | 14 +++++++------- pyaedt/emit_core/results/revision.py | 26 +++++++++++++------------- pyaedt/hfss.py | 2 +- pyaedt/maxwell.py | 2 +- pyaedt/modeler/modeler3d.py | 4 ++-- pyaedt/modules/Boundary.py | 20 ++++++++++---------- 7 files changed, 38 insertions(+), 38 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index afc7c9cd562..7410bf9fa18 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -64,10 +64,10 @@ repos: additional_dependencies: [black==23.9.1] -- repo: https://github.com/numpy/numpydoc - rev: v1.6.0 - hooks: - - id: numpydoc-validation +# - repo: https://github.com/numpy/numpydoc +# rev: v1.6.0 +# hooks: +# - id: numpydoc-validation # - repo: https://github.com/pycqa/pydocstyle # rev: 6.1.1 diff --git a/pyaedt/application/Variables.py b/pyaedt/application/Variables.py index db9694a3947..06d91b48ab2 100644 --- a/pyaedt/application/Variables.py +++ b/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. diff --git a/pyaedt/emit_core/results/revision.py b/pyaedt/emit_core/results/revision.py index f3ecb2f2274..f4fa48f7ddd 100644 --- a/pyaedt/emit_core/results/revision.py +++ b/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 diff --git a/pyaedt/hfss.py b/pyaedt/hfss.py index f3c7ceeffc7..4b466df71ab 100644 --- a/pyaedt/hfss.py +++ b/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 diff --git a/pyaedt/maxwell.py b/pyaedt/maxwell.py index 30ec7877bd1..82d1971c36b 100644 --- a/pyaedt/maxwell.py +++ b/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 diff --git a/pyaedt/modeler/modeler3d.py b/pyaedt/modeler/modeler3d.py index c691e9892ba..48ed3f6288b 100644 --- a/pyaedt/modeler/modeler3d.py +++ b/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") diff --git a/pyaedt/modules/Boundary.py b/pyaedt/modules/Boundary.py index 48572ecbfcc..630fd3937cf 100644 --- a/pyaedt/modules/Boundary.py +++ b/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