Reformat docstrings.rst file

Author: jorgepiloto

doc/source/doc-style/docstrings.rst

@@ -1,5 +1,5 @@
-NumPy Docstrings
-================
+Numpydoc docstrings
+###################
 
 When writing docstrings for PyAnsys libraries, use the `numpydoc`_
 style, regardless as to whether you are using this Sphinx extension or the 
@@ -40,10 +40,11 @@ classes, methods, and variables. For example::
 
 
 Required Docstring Sections
----------------------------
+===========================
+
 PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum:
 
-* `Short description <https://numpydoc.readthedocs.io/en/latest/format.html#short-summary>`_
+* `Short Summary <https://numpydoc.readthedocs.io/en/latest/format.html#short-summary>`_
 * `Extended Summary <https://numpydoc.readthedocs.io/en/latest/format.html#extended-summary>`_ if applicable
 * `Parameters <https://numpydoc.readthedocs.io/en/latest/format.html#parameters>`_ if applicable
 * `Returns <https://numpydoc.readthedocs.io/en/latest/format.html#returns>`_ if applicable
@@ -52,11 +53,29 @@ PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum:
 These sections should follow numpydoc style. To avoid inconsistencies between
 PyAnsys libraries, adhere to the additional style guidelines that follow.
 
-Classes
-~~~~~~~
+
+Short Summary
+-------------
+This is a single-line which goes right after the declaration of the function or
+class and provides a quick overview about the final goal of the code. The
+``short summary`` is mandatory. If 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. Both ways are accepted by `PEP 257
+<https://peps.python.org/pep-0257>`_ but you must be consistent across your
+project. In case you decide to declare the short summary on the same line,
+please refer to :ref:`Numpydoc Validation`, as ``"GL01"`` check needs to be
+disabled.
+
+Depending in whether you are documenting a ``Class`` or a ``function``, you will
+need to apply different ``short-summary`` guidelines.
+
+Short Summary 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 if applicable::
+summary in a new line if applicable::
 
   class FieldAnalysis3D(Analysis):
     """Manages 3D field analysis setup in HFSS, Maxwell 3D, and Q3D.
@@ -67,19 +86,20 @@ summary if applicable::
     ...
     """
 
-
 Ensure that there is a line break between the end of a class docstring and the subsequent methods.
 
-Methods
-~~~~~~~
+Short Summary 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 if applicable::
+by an extended summary in a new line if applicable::
 
   def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None):
-    """Export mesh statistics to a file."""
+    """Export mesh statistics to a file.
+    
+    ...
+    """
       
-
 Methods with a leading underscore (_) are 'protected' methods, meaning that they are not rendered in the
 documentation unless an explicit request is made to add them using Sphinx directives. However, clearly
 written descriptions for private methods are still important.
@@ -91,11 +111,13 @@ add a docstring for the setter. A setter simply exposes both the GET and SET met
 just the GET method. Examples should be included to demonstrate usage.
 
 Parameters
-~~~~~~~~~~
+----------
 Both classes and methods have parameters in their function signatures. All parameters in a function
-signature should appear in the 'Parameters' section for the class or method. 
+signature should appear in the ``Parameters`` section for the class or method. 
+
+Here is an example of a ``Parameters`` section for a class in PyAEDT:
 
-Here is an example of a 'Parameters' section for a class in PyAEDT::
+.. code-block:: rst
 
   Parameters
   ----------
@@ -144,41 +166,81 @@ parameter, the description specifies the default along with any information that
 be needed about the behavior that occurs when the default is used.
 
 Returns
-~~~~~~~
-The 'Returns' section contains only the return data type and a brief description
-that concludes with a period::
+-------
+The ``Returns`` section contains only the return data type and a brief description
+that concludes with a period:
+
+.. code-block:: rst
 
   Returns
   -------
-    dict
+  dict
       Dictionary of components with their absolute paths.
  
 
-A class does not have a 'Returns' section. If a Boolean is returned, format the
-'Returns` section like this::
+A class does not have a ``Returns`` section. If a ``Boolean`` is returned, format the
+``Returns`` section like this:
+
+.. code-block:: rst
 
   Returns
-  --------
-    bool
+  -------
+  bool
       ``True`` when successful, ``False`` when failed.
 
+It is possible for the ``Returns`` section to look like the ``Parameters`` one
+if variable names are provided:
 
-It is possible for more than one item to be returned::
+.. code-block:: rst
 
   Returns
-  --------
-    type
+  -------
+  has_succeeded : bool
+      ``True`` when successful, ``False`` when failed.
+
+It is possible for more than one item to be returned:
+
+.. code-block:: rst
+
+  Returns
+  -------
+  type
       Ground object.
-    str
+  str
       Ground name.
 
-
 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.
 
+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
+<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,
+consider the following function:
+
+.. code-block:: rst
+
+   Examples
+   --------
+   Create an instance of HFSS and connect to an existing HFSS
+   design or create a new HFSS design if one does not exist.
+
+   >>> from pyaedt import Hfss
+   >>> hfss = Hfss()
+   pyaedt info: No project is defined...
+   pyaedt info: Active design is set to...
+
+
+Notice that if the definition of the function gets updated, this
+section needs to be updated too.
+
+
 Example Docstrings
-------------------
+==================
 Methods and functions should generally be documented within the
 'Examples' section to make the usage of the method or function clear.
 Here is a sample function:
@@ -196,26 +258,8 @@ This directive renders the sample function as:
 
 .. autofunction:: pyansys_sphinx_theme.sample_func.func
 
-
-Validation
-----------
-Enable validation of docstrings during the Sphinx build by adding the
-following line to the ``conf.py`` file::
-
-  numpydoc_validation_checks = {"GL08"}
-
-This will issue the following warning for any object without a docstring::
-
-  "The object does not have a docstring"
-
-The ``"GL08"`` code is required at minimum for PyAnsys libraries.
-Other codes may be enforced at a later date. For a full listing,
-see `Validation <https://numpydoc.readthedocs.io/en/latest/validation.html#validation>`_
-in the `numpydoc`_.
-
-
 Additional Information
-----------------------
+======================
 You can find additional information and examples at `numpydoc`_. Reference
 this documentation as the primary source regarding docstring styles for directives
 that are not covered here. For example, you use the ``note::`` directive to highlight

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

@@ -1,5 +1,5 @@
-Formatting Tools
-================
+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