doc/enhance doc practices info (#42)

PipKat · akaszynski · MaxJPRey · web-flow · commit fbfae7cbb79c · 2022-02-07T01:36:43.000Z
* doc/enhance doc practices info

* doc/enhance doc practices info further

* doc/enhance doc practices info further

* Apply suggestions from code review

Co-authored-by: Maxime Rey &lt;87315832+MaxJPRey@users.noreply.github.com&gt;

Co-authored-by: Alex Kaszynski &lt;akascap@gmail.com&gt;
Co-authored-by: Maxime Rey &lt;87315832+MaxJPRey@users.noreply.github.com&gt;
diff --git a/doc/source/documentation_style/docstrings.rst b/doc/source/documentation_style/docstrings.rst
@@ -4,63 +4,180 @@ Docstring Standards
 ###################
 When writing docstrings for PyAnsys libraries, use the `numpydoc`_
 documentation style. To use `numpydoc`_, add the following to your
-``conf.py``:
+``conf.py`` file:
 
 .. code:: python
 
   extensions = ['numpydoc',
                 # other extensions
   ]
 
+For consistency within PyAnsys libraries, always use ``"""`` to introduce and conclude a
+docstring, keeping the line length shorter than 70 characters. Ensure that there are
+no blank spaces at the end of a line because they will cause errors in build checks that you
+will then have to resolve.
 
-Minimum Requirements
---------------------
-PyAnsys library docstrings contain at a minimum the following
-`numpydoc`_ sections:
+A blank line signifies the start of a new paragraph. To create a bulleted or numbered list,
+ensure that there is a blank line before the first item and after the last item. Because you
+use the same markup in your docstrings as you do in RST files, see this `quick reference
+<https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_. 
+
+Surround any text that you want to set apart as literal text in double back ticks to render
+it in a monospace gold font. Use double back ticks to surround the names of files, folders,
+classes, methods, and variables. For example::
+
+  """Initialize the ``Desktop`` class with the version of AEDT to use.``
+
+
+.. note::
+   The PyAnsys style uses two back ticks to surround the names of classes, methods, and
+   variables, not the single back tick that is recommended by the  `numpydoc`_ documentation
+   style. 
+
+ 
+Minimum Section Requirements
+----------------------------
+PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum:
 
 * `Short description <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
 * `Examples <https://numpydoc.readthedocs.io/en/latest/format.html#examples>`_
 
-These sections should follow the numpydoc standards. To avoid
-inconsistencies between PyAnsys libraries, adhere to the additional 
-standards that follow.
+These sections should follow numpydoc standards. To avoid inconsistencies between
+PyAnsys libraries, adhere to the additional standards that follow.
+
+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::
+
+  class FieldAnalysis3D(Analysis):
+    """Manages 3D field analysis setup in HFSS, Maxwell 3D, and Q3D.
+
+    This class is automatically initialized by an application call from one of
+    the 3D tools. For parameter definitions, see the application function.
+
+    ...
+    """
+
+
+Ensure that there is a line break between the end of a class docstring and the subsequent methods.
+
+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::
+
+  def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None):
+    """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, clearing
+documenting private methods is still important.
+
+If a method has the decorator ``@property``, it is turned into a property, which is described as a
+'noun' rather than a 'verb'. Because the resulting property cannot have parameters, you remove
+the 'Parameters' section for this method. If a setter follows the decorator ``@property``, do not
+add a docstring for the setter. A setter simply exposes both the GET and SET methods rather
+just the GET method. Examples should be included to demonstrate usage.
 
 Parameters
 ~~~~~~~~~~
-Always specify the type, and whenever necessary, provide the full class name::
+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. 
+
+Here is an example of a 'Parameters' section for a class in PyAEDT::
 
   Parameters
   ----------
-  my_obj : :class:`ansys.<product>.<library>.FooClass`
-      Description of FooClass.
-  some_int : int
-      Some integer value.
-
-.. note::
-   Parameter descriptions have punctuation. While the brief description itself
-   need not be a sentence, any text following it should a clear, complete
-   sentence. 
-
-
+    application : str
+        3D application that is to initialize the call.
+    projectname : str, optional
+        Name of the project to select or the full path to the project
+        or AEDTZ archive to open. The default is ``None``, in which
+        case an attempt is made to get an active project. If no
+        projects are present, an empty project is created.
+    designname : str, optional
+        Name of the design to select. The default is ``None``, in
+        which case an attempt is made to get an active design. If no
+        designs are present, an empty design is created.
+    solution_type : str, optional
+        Solution type to apply to the design. The default is
+        ``None``, in which case the default type is applied.
+    setup_name : str, optional
+        Name of the setup to use as the nominal. The default is
+        ``None``, in which case the active setup is used or
+        nothing is used.
+    specified_version : str, optional
+        Version of AEDT  to use. The default is ``None``, in which case
+        the active version or latest installed version is used.
+    non_graphical : bool, optional
+        Whether to run AEDT in the non-graphical mode. The default
+        is ``False``, in which case AEDT is launched in the graphical mode.
+    new_desktop_session : bool, optional
+        Whether to launch an instance of AEDT in a new thread, even if
+        another instance of the ``specified_version`` is active on the
+        machine. The default is ``True``.
+    close_on_exit : bool, optional
+        Whether to release  AEDT on exit. The default is ``False``.
+    student_version : bool, optional
+        Whether to enable the student version of AEDT. The default
+        is ``False``.
+    
+The name of each parameter is followed by a space, a colon, a space, and then
+the data type. A parameter is optional if its keyword argument has a default shown
+in the function signature. For an optional parameter, the data type is followed by a
+comma and ``optional``.
+
+The brief description for a parameter is generally a sentence fragment. However, 
+additional information is provided in clear, complete sentences. For an optional
+parameter, the description specifies the default along with any information that might
+be needed about the behavior that occurs when the default is used.
+  
 Returns
 ~~~~~~~
-The Returns section contains only the return type and (not the name and type)
-and a brief description::
+The 'Returns' section contains only the return data type and a brief description
+that concludes with a period::
 
   Returns
   -------
-  int
-      Description of some return value.
+    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::
+
+  Returns
+  --------
+    bool
+      ``True`` when successful, ``False`` when failed.
+
+
+It is possible for more than one item to be returned::
+
+  Returns
+  --------
+    type
+      Ground object.
+    str
+      Ground name.
+
+
+If a method does not have a decorator, the basic implementation of Python
+methods is used. In this case, ``None`` is returned but you do not document it.
+Consequently, such a method does not have a 'Returns' section.
 
 Example Docstrings
 ------------------
 Methods and functions should generally be documented within the
-``Examples`` docstring section to make the usage of the method or
-function clear.  Here is a sample function:
+'Examples' section to make the usage of the method or function clear.
+Here is a sample function:
 
 .. literalinclude:: sample_func.py
 
@@ -79,25 +196,28 @@ This directive renders the sample function as:
 Validation
 ----------
 Enable validation of docstrings during the Sphinx build by adding the
-following line to ``conf.py``::
+following line to the ``conf.py`` file::
 
   numpydoc_validation_checks = {"GL08"}
 
-This will issue the following warning for any objects without a docstring::
+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
-`numpydoc Validation Check
-<https://numpydoc.readthedocs.io/en/latest/validation.html#validation>`_.
+Other codes may be enforced at a later date. For a full listing, in the `numpydoc`_,
+see the `Validation <https://numpydoc.readthedocs.io/en/latest/validation.html#validation>`_
+topic.
 
 
 Additional Information
 ----------------------
 Additional examples and notes can be found at `numpydoc`_. Reference
 this documentation as the primary source of information regarding
-docstring styles for directives not covered here.
+docstring styles for directives that are not covered here. For example,
+you would use the ``note::`` directive to highlight important information
+and the ``warning::`` directive to point out an action that might result
+in data loss.
 
 .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
 .. _googledoc: https://google.github.io/styleguide/
diff --git a/doc/source/documentation_style/index.rst b/doc/source/documentation_style/index.rst
@@ -26,7 +26,7 @@ The documentation for a PyAnsys library should contain:
   :ref:`docstrings`.
 * Full gallery of examples. See `PyMAPDL Examples
   <https://mapdldocs.pyansys.com/examples/index.html>`_
-* User guide for the library.
+* Developer's guide for the library.
 * Link to this developer's guide.
 
 .. toctree::
diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst
@@ -2,9 +2,23 @@
 
 Documentation Practices
 =======================
-The generation of documentation uses `Sphinx <https://www.sphinx-doc.org/en/master/>`__
-and an Ansys-branded theme. Documentation is built from docstrings, reStructuredText
-(RST) files, and Python (PY) example files.
+PyAnsys documentation must not only be written but also maintained. If you are new
+to writing developer documentation, see the `Google Developer Documentation Style
+Guide <https://developers.google.com/style/articles>`_. It provides editorial guidelines
+for writing clear and consistent developer documentation, allowing this guide to supply
+guidance specific to PyAnsys library documentation.
+
+When writing developer documentation, the relationship between code and documenation is
+key. To keep documentation up to date with rapdily evolving code:
+
+- Minimize the content footprint
+- Write `timeless documentation <https://developers.google.com/style/timeless-documentation>`_
+- Support contributions from both inside and outside of the development team
+- Perform periodic reviews
+
+The generation of PyAnsys documentation uses `Sphinx <https://www.sphinx-doc.org/en/master/>`__ 
+and an Ansys-branded theme (pyansys-sphinx-theme) to assemble content comes from docstrings,
+reStructuredText (RST) files, and Python (PY) example files.
 
 Docstrings
 ----------
@@ -28,7 +42,10 @@ style docstrings, refers you to the `Google Python Style Guide <https://google.g
 
 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:`api_documentation`.
+across PyAnsys libraries. For more information, see:
+
+- :ref:`docstrings`
+- :ref:`api_documentation`
 
 RST Files
 ---------
@@ -57,16 +74,29 @@ index file referenced for each section must be named ``index.rst``. If you open
 in ``doc\source\overview``, you can see that it describes how the PyAnsys project provides
 Python libraries that expose Ansys technologies to the Python ecosystem. 
 
-After you build documenatation locally as described in :ref:`doc_building`, the first-level
+After you build documentation locally as described in :ref:`doc_building`, the first-level
 heading in the ``index.rst`` file for each docuemntation section is shown as clickable link
-in the header of the documentation's generated HTML output.
-
-You can nest RST files. Plenty of examples of nested RST files are available in the PyAnsys
-libraries on GitHub. Because you need to be familiar with the content in the *PyAnsys Developer's
-Guide*, paging through this doc and exploring its repository will help you better
-understand how RST files are used. For more information on defining documentation
-structure, see the `Sphinx Getting Started <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_
-documentation.
+in the header of the documentation's generated HTML output. For more information on defining
+a documentation structure, see the `Sphinx Getting Started <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_
+guide.
+
+Within RST files, heading titles are followed by a line having a string of characters that is
+the same length as the heading title. If the length of the characters
+under the heading title do not match the length of the heading title, Sphinx will generate a warning.
+
+For consistency within PyAnsys libraries, the use of these special characters is recommended for
+headings but are not enforced:
+
+- For first-level headings, use ====.
+- For second-level headings, use ---.
+- For third-level headings, use ~~~. 
+
+For comprehensive syntax information, see the `reStrucutredText Markup Specification
+<https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_.
+
+Because you need to be familiar with the content in the *PyAnsys Developer's Guide*, page through
+its HTML pages and then explore the RST files in its repository. This will help you to understand
+the syntax and see how RST files are nested to create this guide. 
 
 Examples
 --------
diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst
@@ -18,7 +18,7 @@ These libraries play a vital role in:
 - Workflow orchestration
 - Data manipulation and export
 
-The libraries also include plugins and interfaces to the vast python
+The libraries also include plugins and interfaces to the vast Python
 ecosystem. Examples include:
 
 - Arrays using `NumPy <https://numpy.org/>`_
@@ -28,10 +28,13 @@ ecosystem. Examples include:
 - Advanced scientific computing using `SciPy <https://www.scipy.org/>`_
 - Machine learning using `TensorFlow <https://www.tensorflow.org/>`_
 
+.. note::
+   If you are new to GitHub, we suggest that you visit `The ReadMe Project <https://github.com/readme>`_.
+   It is a dedicated platform for highlighting the best from the open source software community.
+   Monthly newletters provide feature articles, developer stories, guides, and podcasts.
 
 Project Organization
 ~~~~~~~~~~~~~~~~~~~~
-
 The PyAnsys project is hosted on GitHub at `PyAnsys
 <https://github.com/pyansys>`_. It contains several repositories with 
 Python libraries that interface with Ansys products or services. 
@@ -48,7 +51,7 @@ If you want to create, develop, or contribute to a PyAnsys library,
 visit these links:
 
 * `PyAnsys Project Developer's Guide <https://github.com/pyansys/about>`_
-* `PyAnsys Documentation Theme <https://github.com/pyansys/pyansys-sphinx-theme>`_
+* `PyAnsys Sphinx Theme Documentation <https://github.com/pyansys/pyansys-sphinx-theme>`_
 * `gRPC Hello-world Example <https://github.com/pyansys/pyansys-helloworld>`_
 * `Material Example Data <https://github.com/pyansys/example-data>`_
 
