Apply code suggestions

Author: jorgepiloto

doc/source/doc-style/docstrings.rst

@@ -44,26 +44,26 @@ PyAnsys libraries, adhere to the additional style guidelines that follow.
 
 Short Summary
 -------------
-This is a single-line that goes right after the declaration of the class or
-function for briefly describing what the class or function or does. The
+This is a single line that goes immediately after the declaration of the class
+or function to briefly describe what the class or function does. The
 `short summary` is mandatory. If it is not present, :ref:`Doc Style Tools` will
 raise an error.
 
 The short summary can be declared on the same line as the opening quotes or on
 the next line. While `PEP 257
 <https://peps.python.org/pep-0257>`_ accepts both ways, you must be consistent across your
 project. If you decide to declare the short summary on the same line,
-refer to :ref:`Numpydoc Validation` because the ``"GL01"`` check needs to be
+refer to :ref:`Numpydoc Validation` because the ``"GL01"`` check must be
 disabled.
 
-Depending in whether you are documenting a ``Class`` or a ``function``, you will
-need to apply different ``short-summary`` guidelines.
+The guidelines for documenting short summaries differ for classes versus
+functions.
 
-Short Summary for Classes
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Short Summaries for Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A class is a 'noun' representing a collection of methods. For consistency within PyAnsys libraries,
 always start the brief description for a class with a verb ending in 's', followed by an extended
-summary in a new line if applicable::
+summary in a new line if additional information is needed::
 
   class FieldAnalysis3D(Analysis):
     """Manages 3D field analysis setup in HFSS, Maxwell 3D, and Q3D.
@@ -76,11 +76,11 @@ summary in a new line if applicable::
 
 Ensure that there is a line break between the end of a class docstring and the subsequent methods.
 
-Short Summary for Methods
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Short Summaries for Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A method is a 'verb' representing an action that can be performed. For consistency within PyAnsys
 libraries, always start the brief description for a method with a verb not ending in 's', followed
-by an extended summary in a new line if applicable::
+by an extended summary in a new line if additional information is needed::
 
   def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None):
     """Export mesh statistics to a file.
@@ -176,7 +176,7 @@ A class does not have a ``Returns`` section. If a ``Boolean`` is returned, forma
   bool
       ``True`` when successful, ``False`` when failed.
 
-It is possible for the ``Returns`` section to look like the ``Parameters`` one
+It is possible for the ``Returns`` section to look like the ``Parameters`` section
 if variable names are provided:
 
 .. code-block:: rst
@@ -199,15 +199,15 @@ It is possible for more than one item to be returned:
 
 If a method does not have a decorator, the basic implementation of Python
 methods is used. In this case, while ``None`` is returned, you do not document it.
-Consequently, such a method does not have a 'Returns' section.
+Consequently, such a method does not have a ``Returns`` section.
 
 Examples
 --------
 
 The ``Examples`` section provides a quick reference on how to use a method or
-function. This section needs to be compliant with the `doctest
+a function. This section must be compliant with the `doctest
 <https://docs.python.org/3/library/doctest.html>`_ format and is not supposed to
-be a replacement of your test suite but a complement to it. An an example,
+replace your test suite but complement it. As an example,
 consider the following function:
 
 .. code-block:: rst
@@ -223,8 +223,8 @@ consider the following function:
    pyaedt info: Active design is set to...
 
 
-Notice that if the definition of the function gets updated, this
-section needs to be updated too.
+If the definition of the function is updated, this
+section must be updated too.
 
 
 Additional Directives

doc/source/doc-style/formatting-tools.rst

@@ -1,6 +1,5 @@
 Doc Style Tools
 ===============
-
 There are plenty of tools for documentation style and coverage. This section
 presents some of the most popular ones in the Python ecosystem. A minimum
 configuration is provided for each one so you can easily include them in your
@@ -15,7 +14,7 @@ Blacken-Docs
 ------------
 
 When writing documentation, it is frequent to include code-blocks which are used
-as examples. However, these code snippets cannot be tested with the usual code
+as examples. However, these code snippets style cannot be verified with the usual code
 formatting tools. This is where `blacken-docs`_ comes into play. You can execute
 this tool by running:
 
@@ -87,13 +86,13 @@ for source code coverage.
 
 Numpydoc Validation
 -------------------
-In order to validate the style of :ref:`Numpydoc Docstrings`, it is possible to
-take advantage of `numpydoc`_ Sphinx extension. Note that this extension will
-only check for those objcts whose docstring needs to be rendered. It is not a
-command line tool which checks all docstrings style in your source code.
+To validate the style of :ref:`Numpydoc Docstrings`, it is possible to
+take advantage of the `numpydoc`_ Sphinx extension. Note that this extension
+checks only for those objects whose docstrings must be rendered. It is not a
+command line tool that checks the style of all docstrings in your source code.
 
-Because it is a Sphinx extension, it needs to be configured via through the
-``conf.py``.  see :ref:`The \`\`doc/\`\` directory`. Start by adding it to the
+Because `numpydoc`_ is a Sphinx extension, it must be configured in the
+``conf.py`` file.  See :ref:`The \`\`doc/\`\` directory`. Start by adding it to the
 list of extensions:
 
 .. code-block:: python
@@ -103,7 +102,7 @@ list of extensions:
       ...
   ]
 
-Once added, you can select which `validation checks
+Once the `numpydoc`_ extension is added, you can select which `validation checks
 <https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks>`_
 need to be addressed by using the ``numpydoc_validation_checks`` dictionary:
 
@@ -117,7 +116,7 @@ This will issue the following warning for any object without a docstring:
 
    "The object does not have a docstring"
 
-For a complete list of available checks, please check the `full mapping of
+For a complete list of available checks, see the `full mapping of
 validation checks
 <https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks>`_.
 

doc/source/guidelines/doc_practices.rst

@@ -53,7 +53,7 @@ Google style docstrings, refers you to the `Google Python Style Guide
 
 Regardless of the extension that you choose for generating documentation, we
 recommend the use of numpy-style docstrings so that there is consistency
-across PyAnsys libraries. For more information, see :ref:`Documentation Style`.
+within PyAnsys libraries. For more information, see :ref:`Documentation Style`.
 
 RST Files
 ~~~~~~~~~
@@ -249,7 +249,7 @@ For example, the Granta MI BoM Analytics
 :external+grantami-bomanalytics:doc:`Part Compliance page <api/compliance/parts>`
 first describes the
 :external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics.queries.PartComplianceQuery`
-class, and then describes the
+class, and then it describes the
 :external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics._query_results.PartComplianceQueryResult`,
 and
 :external+grantami-bomanalytics:class:`~ansys.grantami.bomanalytics._item_results.PartWithComplianceResult`