From e33d22cbcf6e7a61006ccb1584f0b5a424ff47e4 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 24 Oct 2023 18:34:07 +0800 Subject: [PATCH] Adding numpydoc hook (#2381) * Implementing numpy hook * typo * Update .pre-commit-config.yaml * Update .pre-commit-config.yaml * Update .pre-commit-config.yaml * Update .pre-commit-config.yaml * Fixing hook configuration * Adapting partially the docs to the hook * Changing header --- .pre-commit-config.yaml | 13 ++++ pyproject.toml | 69 ++++++++++++++++++- .../mapdl/core/_commands/preproc/elements.py | 2 +- src/ansys/mapdl/core/common_grpc.py | 4 +- src/ansys/mapdl/core/errors.py | 2 +- src/ansys/mapdl/core/launcher.py | 6 +- src/ansys/mapdl/core/logging.py | 4 +- src/ansys/mapdl/core/mapdl.py | 6 +- src/ansys/mapdl/core/mapdl_corba.py | 2 +- src/ansys/mapdl/core/mapdl_grpc.py | 4 +- src/ansys/mapdl/core/mesh_grpc.py | 4 +- src/ansys/mapdl/core/parameters.py | 6 +- src/ansys/mapdl/core/plotting.py | 14 ++-- src/ansys/mapdl/core/post.py | 5 +- src/ansys/mapdl/core/xpl.py | 3 +- 15 files changed, 113 insertions(+), 31 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6036af92c2..eb59122236 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,6 +7,19 @@ repos: hooks: - id: isort +- repo: https://github.com/numpy/numpydoc + rev: v1.6.0 + hooks: + - id: numpydoc-validation + exclude: | + (?x)( + tests/| + examples| + doc/source/| + src/ansys/mapdl/core/_commands| + src/ansys/mapdl/core/commands + ) + - repo: https://github.com/psf/black rev: 23.9.1 # IF VERSION CHANGES --> MODIFY "blacken-docs" MANUALLY AS WELL!! hooks: diff --git a/pyproject.toml b/pyproject.toml index 900e10a19f..99eab51f26 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -155,4 +155,71 @@ show_missing = true skip = '*.pyc,*.txt,*.gif,*.png,*.jpg,*.js,*.html,*.doctree,*.ttf,*.woff,*.woff2,*.eot,*.mp4,*.inv,*.pickle,*.ipynb,flycheck*,./.git/*,./.hypothesis/*,*.yml,./doc/build/*,./doc/images/*,./dist/*,*~,.hypothesis*,./doc/source/examples/*,*cover,*.dat,*.mac,*.cdb,*.CDB,build,./docker/mapdl/v*,./factory/*,./ansys/mapdl/core/mapdl_functions.py,PKG-INFO,*.mypy_cache/*,./docker/mapdl/*,./_unused/*' ignore-words = "doc/styles/Vocab/ANSYS/accept.txt" quiet-level = 3 -ignore-regex=".*codespell-ignore$|NORML|POIN" \ No newline at end of file +ignore-regex=".*codespell-ignore$|NORML|POIN" + +[tool.numpydoc_validation] +checks = [ + #"all", # report on all checks, except the below + # "GL01", # "Docstring text (summary) should start in the line immediately " + # "after the opening quotes (not in the same line, or leaving a " + # "blank line in between)", + # "GL02", # "Closing quotes should be placed in the line after the last text " + # "in the docstring (do not close the quotes in the same line as " + # "the text, or leave a blank line between the last text and the " + # "quotes)", + # "GL03", # "Double line break found; please use only one blank line to " + # "separate sections or paragraphs, and do not leave blank lines " + # "at the end of docstrings", + "GL05", # 'Tabs found at the start of line "{line_with_tabs}", please use ' + # "whitespace only", + # "GL06", # 'Found unknown section "{section}". Allowed sections are: ' + # "{allowed_sections}", + "GL07", # "Sections are in the wrong order. Correct order is: {correct_sections}", + # "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", + # "SS01", # "No summary found (a short summary in a single line should be " + # "present at the beginning of the docstring)", + "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 " + # '(e.g. use "Generate" instead of "Generates")', + # "SS06", # "Summary should fit in a single line", + # "ES01", # "No extended summary found", + # "PR01", # "Parameters {missing_params} not documented", + # "PR02", # "Unknown parameters {unknown_params}", + "PR03", # "Wrong parameters order. Actual: {actual_params}. " + # "Documented: {documented_params}", + # "PR04", # 'Parameter "{param_name}" has no type', + "PR05", # 'Parameter "{param_name}" type should not finish with "."', + "PR06", # 'Parameter "{param_name}" type should use "{right_type}" instead ' + # 'of "{wrong_type}"', + "PR07", # 'Parameter "{param_name}" has no description', + # "PR08", # 'Parameter "{param_name}" description should start with a ' + # "capital letter", + # "PR09", # 'Parameter "{param_name}" description should finish with "."', + # "PR10", # 'Parameter "{param_name}" requires a space before the colon ' + # "separating the parameter name and type", + # "RT01", # "No Returns section found", + # "RT02", # "The first line of the Returns section should contain only the " + # "type, unless multiple values are being returned", + # "RT03", # "Return value has no description", + # "RT04", # "Return value description should start with a capital letter", + # "RT05", # 'Return value description should finish with "."', + "YD01", # "No Yields section found", + # "SA01", # "See Also section not found", + "SA02", # "Missing period at end of description for See Also " + # '"{reference_name}" reference', + "SA03", # "Description should be capitalized for See Also " + # '"{reference_name}" reference', + "SA04", # 'Missing description for See Also "{reference_name}" reference', + # "EX01", # "No examples section found", +] + + +override_SS05 = [ # override SS05 to allow docstrings starting with these words + # '^Process ', + # '^Assess ', + # '^Access ', +] diff --git a/src/ansys/mapdl/core/_commands/preproc/elements.py b/src/ansys/mapdl/core/_commands/preproc/elements.py index d9645fc769..3fc1304ccf 100644 --- a/src/ansys/mapdl/core/_commands/preproc/elements.py +++ b/src/ansys/mapdl/core/_commands/preproc/elements.py @@ -1241,7 +1241,7 @@ def eplot(self, **kwargs): APDL Command: EPLOT Notes - ------ + ----- Produces an element display of the selected elements. In full graphics, only those elements faces with all of their corresponding nodes selected are plotted. In PowerGraphics, all element faces of the selected diff --git a/src/ansys/mapdl/core/common_grpc.py b/src/ansys/mapdl/core/common_grpc.py index 16c242f1e4..62408fc188 100644 --- a/src/ansys/mapdl/core/common_grpc.py +++ b/src/ansys/mapdl/core/common_grpc.py @@ -104,7 +104,7 @@ def check_vget_input(entity: str, item: str, itnum: str) -> str: Returns ------- - command : str + str MAPDL formatted vget command after the "VGET, " in the format of: "ENTITY, , ITEM, ITNUM" """ @@ -158,7 +158,7 @@ def parse_chunks(chunks, dtype=None): Returns ------- - array : np.ndarray + np.ndarray Deserialized numpy array. """ diff --git a/src/ansys/mapdl/core/errors.py b/src/ansys/mapdl/core/errors.py index e61fffbaad..023e99b455 100644 --- a/src/ansys/mapdl/core/errors.py +++ b/src/ansys/mapdl/core/errors.py @@ -1,4 +1,4 @@ -"""pymapdl specific errors""" +"""PyMAPDL specific errors""" from functools import wraps import signal diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index a50a4758d9..a11834df37 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1079,15 +1079,15 @@ def launch_mapdl( ``log_apdl='pymapdl_log.txt'``). By default this is disabled. remove_temp_files : bool, optional - .. deprecated:: 0.64.0 - Use argument ``remove_temp_dir_on_exit`` instead. - When ``run_location`` is ``None``, this launcher creates a new MAPDL working directory within the user temporary directory, obtainable with ``tempfile.gettempdir()``. When this parameter is ``True``, this directory will be deleted when MAPDL is exited. Default ``False``. + .. deprecated:: 0.64.0 + Use argument ``remove_temp_dir_on_exit`` instead. + remove_temp_dir_on_exit : bool, optional When ``run_location`` is ``None``, this launcher creates a new MAPDL working directory within the user temporary directory, obtainable with diff --git a/src/ansys/mapdl/core/logging.py b/src/ansys/mapdl/core/logging.py index 2c9d38c3f9..e695181047 100644 --- a/src/ansys/mapdl/core/logging.py +++ b/src/ansys/mapdl/core/logging.py @@ -10,8 +10,8 @@ outputs and it is used to track the different MAPDL instances. -Usage ------ +How to use +========== Global logger ~~~~~~~~~~~~~ diff --git a/src/ansys/mapdl/core/mapdl.py b/src/ansys/mapdl/core/mapdl.py index 5ea89026c6..1ba922e538 100644 --- a/src/ansys/mapdl/core/mapdl.py +++ b/src/ansys/mapdl/core/mapdl.py @@ -3002,6 +3002,8 @@ def run_multiline(self, commands) -> str: This function is being deprecated. Please use `input_strings` instead. + Allows to run multiple mapdl commands in different lines in one go. + Parameters ---------- commands : str @@ -3642,7 +3644,7 @@ def directory(self, path: Union[str, pathlib.Path]) -> None: @property def _lockfile(self): - """lockfile path""" + """Lockfile path""" path = self.directory if path is not None: return os.path.join(path, self.jobname + ".lock").replace("\\", "/") @@ -3885,7 +3887,7 @@ def _screenshot_path(self): return filenames[-1] def _set_log_level(self, level): - """alias for set_log_level""" + """Alias for set_log_level""" self.set_log_level(level) def list(self, filename, ext=""): diff --git a/src/ansys/mapdl/core/mapdl_corba.py b/src/ansys/mapdl/core/mapdl_corba.py index 39f1bf3f0b..e596421797 100644 --- a/src/ansys/mapdl/core/mapdl_corba.py +++ b/src/ansys/mapdl/core/mapdl_corba.py @@ -414,7 +414,7 @@ def _run(self, command, **kwargs): return response def _close_output(self): - """closes the output file""" + """Closes the output file""" self._output = "" if self._outfile: self._outfile.close() diff --git a/src/ansys/mapdl/core/mapdl_grpc.py b/src/ansys/mapdl/core/mapdl_grpc.py index dce09f08b2..b13e3e5ed0 100644 --- a/src/ansys/mapdl/core/mapdl_grpc.py +++ b/src/ansys/mapdl/core/mapdl_grpc.py @@ -1,4 +1,4 @@ -"""gRPC specific class and methods for the MAPDL gRPC client """ +"""A gRPC specific class and methods for the MAPDL gRPC client """ import fnmatch from functools import wraps @@ -2473,7 +2473,7 @@ def _get_array( kloop="", **kwargs, ): - """gRPC VGET request. + """Do a gRPC VGET request. Send a vget request, receive a bytes stream, and return it as a numpy array. diff --git a/src/ansys/mapdl/core/mesh_grpc.py b/src/ansys/mapdl/core/mesh_grpc.py index 2568606fe0..f29849a62b 100644 --- a/src/ansys/mapdl/core/mesh_grpc.py +++ b/src/ansys/mapdl/core/mesh_grpc.py @@ -543,7 +543,7 @@ def _load_nodes(self, chunk_size=DEFAULT_CHUNKSIZE): Returns ------- - nodes : np.ndarray + np.ndarray Numpy array of nodes """ if self._chunk_size: @@ -655,7 +655,7 @@ def _load_element_types(self, chunk_size=DEFAULT_CHUNKSIZE): Parameters ---------- - chunk_size : int + int Size of the chunks to request from the server. """ request = anskernel.StreamRequest(chunk_size=chunk_size) diff --git a/src/ansys/mapdl/core/parameters.py b/src/ansys/mapdl/core/parameters.py index da1dda442c..3b7487184b 100644 --- a/src/ansys/mapdl/core/parameters.py +++ b/src/ansys/mapdl/core/parameters.py @@ -535,12 +535,12 @@ def _set_parameter_array(self, name, arr): Parameters ---------- - arr : np.ndarray or List - Array to send to MAPDL. Maximum of 3 dimensions. - name : str Name of the array to write to within MAPDL. + arr : np.ndarray or List + Array to send to MAPDL. Maximum of 3 dimensions. + Examples -------- Load a 1D numpy array into MAPDL diff --git a/src/ansys/mapdl/core/plotting.py b/src/ansys/mapdl/core/plotting.py index 27a7191ba1..490ecb9bbb 100644 --- a/src/ansys/mapdl/core/plotting.py +++ b/src/ansys/mapdl/core/plotting.py @@ -224,13 +224,13 @@ def _general_plotter( ``off_screen`` are evaluated to ``False`` and ``True`` respectively. - style : string, optional + style : str, optional Visualization style of the mesh. One of the following: ``style='surface'``, ``style='wireframe'``, ``style='points'``. Defaults to ``'surface'``. Note that ``'wireframe'`` only shows a wireframe of the outer geometry. - color : string or 3 item list, optional + color : str, list[int, int, int], optional Use to make the entire mesh have a single solid color. Either a string, RGB list, or hex color string. For example: ``color='white'``, ``color='w'``, ``color=[1, 1, 1]``, or @@ -241,9 +241,9 @@ def _general_plotter( Shows the edges of a mesh. Does not apply to a wireframe representation. - edge_color : string or 3 item list, optional, defaults to black + edge_color : str, list[int, int, int], optional The solid color to give the edges when ``show_edges=True``. - Either a string, RGB list, or hex color string. + Either a string, RGB list, or hex color string. Defaults to black. point_size : float, optional Point size of any nodes in the dataset plotted. Also applicable @@ -594,13 +594,13 @@ def general_plotter( savefig : str, optional Saves screenshot to a file path. - style : string, optional + style : str, optional Visualization style of the mesh. One of the following: ``style='surface'``, ``style='wireframe'``, ``style='points'``. Defaults to ``'surface'``. Note that ``'wireframe'`` only shows a wireframe of the outer geometry. - color : string or 3 item list, optional + color : str, list[int, int, int], optional Use to make the entire mesh have a single solid color. Either a string, RGB list, or hex color string. For example: ``color='white'``, ``color='w'``, ``color=[1, 1, 1]``, or @@ -611,7 +611,7 @@ def general_plotter( Shows the edges of a mesh. Does not apply to a wireframe representation. - edge_color : string or 3 item list, optional, + edge_color : str, list[int, int, int], optional The solid color to give the edges when ``show_edges=True``. Either a string, RGB list, or hex color string. Defaults to black. diff --git a/src/ansys/mapdl/core/post.py b/src/ansys/mapdl/core/post.py index 57022832d0..702a6c676a 100644 --- a/src/ansys/mapdl/core/post.py +++ b/src/ansys/mapdl/core/post.py @@ -113,11 +113,11 @@ def _mapdl(self): @property def _log(self): - """alias for mapdl log""" + """Alias for mapdl log""" return self._mapdl._log def _set_log_level(self, level): - """alias for mapdl._set_log_level""" + """Alias for mapdl._set_log_level""" return self._mapdl._set_log_level(level) @supress_logging @@ -1346,6 +1346,7 @@ def plot_element_stress( **kwargs : dict, optional Keyword arguments passed to :func:`general_plotter ` + Returns ------- pyvista.plotting.renderer.CameraPosition diff --git a/src/ansys/mapdl/core/xpl.py b/src/ansys/mapdl/core/xpl.py index 1d5b219877..5c305a0e15 100644 --- a/src/ansys/mapdl/core/xpl.py +++ b/src/ansys/mapdl/core/xpl.py @@ -362,8 +362,7 @@ def save(self): return response def extract(self, recordname, sets="ALL", asarray=False): - """ - Import a Matrix/Vector from a MAPDL result file. + """Import a Matrix/Vector from a MAPDL result file. At the moment, this only supports reading the displacement vectors from a result file.