Doc/fix minor formatting and style issues

doc/source/coding-style/index.rst

@@ -25,7 +25,7 @@ formatting with the libraries for the "big three" data science packages: `NumPy`
 The purpose of this section is not to repeat coding style documentation
 but rather to describe coding best practices applicable to the `PyAnsys`_ project when there are any
 delineations, clarifications, or additional procedures above and
-beyond `PEP 8`_. For example, this section provides a topic on deprecation
+beyond PEP 8. For example, this section provides a topic on deprecation
 best practices because there is no official guidance on deprecating features
 within Python. 
 

doc/source/coding-style/pep8.rst

@@ -2,9 +2,9 @@ PEP 8
 =====
 
 This section summarizes important coding style guidelines from `PEP 8`_
-and how they apply to PyAnsys libraries. The Python community devised `PEP 8`_ 
+and how they apply to PyAnsys libraries. The Python community devised PEP 8 
 to increase the readability of Python code. Some of the most popular
-packages within the Python ecosystem have adopted `PEP 8`_,
+packages within the Python ecosystem have adopted PEP 8,
 including `NumPy`_, `SciPy`_, and `pandas`_.
 
 Imports
@@ -177,7 +177,7 @@ global rules to determine the correct names:
 Variables
 ~~~~~~~~~
 
-Do not use the characters ``"l"`, ``"O"``, or ``"I"`` as single-character
+Do not use the characters ``"l"``, ``"O"``, or ``"I"`` as single-character
 variable names. In some fonts, these characters are indistinguishable from the
 numerals one and zero.
 
@@ -424,7 +424,7 @@ letter.
 Here are general guidelines for writing comments:
 
 - Always try to explain yourself in code by making it
-   self-documenting with clear variable names.
+  self-documenting with clear variable names.
 - Don't be redundant.
 - Don't add obvious noise.
 - Don't use closing brace comments.

doc/source/conf.py

@@ -16,7 +16,7 @@
 from sphinx_gallery.sorting import FileNameSortKey
 
 # Project information
-project = "PyAnsys Developer's Guide"
+project = "PyAnsys developer's guide"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "Ansys Inc."
 release = version = datetime.now().strftime("%Y-%m-%d")

doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst

@@ -23,8 +23,9 @@ template, the ``extensions`` variable lists these extensions by default:
 Extensions with names beginning with ``sphinx_ext`` are native (built-in) and are
 available for Sphinx's use without any additional installation. Extensions with names
 that do not begin with ``sphinx_ext`` are external extensions and require installation.
-If an extension is not configured properly, attempts to build the documentation fail
-because Sphinx cannot find the needed extension.
+If a non-native extension is not installed but added to the :file:`conf.py` file in the
+``doc/source`` directory, attempts to build the documentation fail because Sphinx cannot
+find the needed extension.
 
 .. _links_to_objects_in_other_doc:
 
@@ -131,9 +132,16 @@ the external `sphinx-design <Sphinx_ext_sphinx_design_>`_ extension for use:
 
      python -m pip install <external-extension-name>
 
-   For example, to install the external ``sphinx-design`` extension, run this command::
+   Examples follow for some of the external extensions mentioned in this
+   documentation.
+
+   - To install the external ``sphinx-design`` extension, run this command::
+
+        python -m pip install sphinx-design
 
-     python -m pip install sphinx-design
+   - To install the external ``sphinx_toolbox.collapse`` extension, run this command::
+
+        python -m pip install sphinx_toolbox.collapse
 
 #. Add the external extension to the ``extensions`` variable in your project's
    :file:`conf.py` file.
@@ -151,8 +159,8 @@ building the documentation. Depending on the project's configuration, you list t
 packages in either the :file:`pyproject.toml` file or the :file:`requirements_doc_txt`
 file.
 
-``pyproject.toml`` file
-~~~~~~~~~~~~~~~~~~~~~~~
+The ``pyproject.toml`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Most projects specify documentation requirements in a :file:`pyproject.toml` file, which
 resides in the root folder. In this file, the ``doc`` variable defines the required ``pip``
@@ -183,8 +191,8 @@ packages and their versions like this.
        "vtk==9.2.6",
    ]
 
-``requirements_doc_txt`` file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``requirements_doc_txt`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Some projects specify documentation requirements in a :file:`requirements_doc_txt`
 file. The root folder of such a project typically has a ``requirements`` directory
@@ -213,14 +221,16 @@ Learn more about extensions
 ---------------------------
 
 As you can see, PyAnsys projects add many extensions to their :file:`conf.py` files
-and documentation requirements. Here are some additional extensions that you might see:
+and documentation requirements. Here are some other native and non-native extensions
+that you might see:
 
 - ``sphinx.ext.coverage``
 - ``sphinx.ext.doctest``
 - ``sphinx.ext.extlinks``
 - ``sphinx.ext.graphviz``
 - ``sphinx.ext.napoleon``
 - ``sphinx.ext.viewcode``
+- ``sphinx_toolbox.collapse``
 
 For more information on extensions, see `Extensions <Sphinx_extensions_>`_ in the
 Sphinx documentation. In addition to the external (third-party) extensions collected

doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst

@@ -28,7 +28,7 @@ and lines where you must resolve them.
 
 Your objective should always be to eliminate or mitigate issues before creating
 or pushing changes to a PR. For example, running ``pre-commit`` and Vale locally
-allows you to proactively resolve typos and trailing whitespaces. However,
+lets you proactively resolve typos and trailing whitespaces. However,
 oftentimes, you must resolve issues that cause the checks run by the CI/CD
 process to fail.
 

doc/source/content-writing/content-how-tos/view-revision-history.rst

@@ -3,7 +3,7 @@
 View revision history on GitHub
 ===============================
 
-GitHub *blame* is a feature that allows you to view the revision history of a
+GitHub *blame* is a feature that lets you view the revision history of a
 file in a repository to see who made changes and when these changes were
 made. You can use the GitHub blame feature for a variety of use cases, including
 these:

doc/source/content-writing/content-how-tos/work-around-Vale.rst

@@ -6,7 +6,7 @@ Work around Vale issues
 Some issues that Vale raises may not be considered problematic in PyAnsys
 projects. This page describes some common workarounds.
 
-Turn Vale on and off
+Turn Vale off and on
 --------------------
 
 If Vale flags content as an issue but you know that this content is
@@ -19,10 +19,10 @@ before the flagged content and then back on again after it::
 
     .. vale on
 
-As shown in the preceding example , you must insert blank lines to separate the
-directives for tuning Vale off and off from your documentation content.
+As shown in the preceding example, you must insert blank lines to separate the
+directives for tuning Vale off and on from your documentation content.
 
-In an MD file, the syntax for these two Vale directives looks like this::
+In an Markdown (MD) file, the syntax for these two Vale directives looks like this::
 
     <!-- vale off -->
 

doc/source/content-writing/examples-writers/index.rst

@@ -3,8 +3,8 @@
 Content in examples
 ===================
 
-Many PyAnsys libraries have an "Example" section. The `sphinx_gallery <Sphinx_ext_sphinx_gallery_>`_
-extension (Sphinx-Gallery) are typically used to generate standalone, downloadable Python scripts
+Many PyAnsys libraries have an "Example" section. The `Sphinx-Gallery <Sphinx_ext_sphinx_gallery_>`_
+extension (``sphinx_gallery``) is typically used to generate standalone, downloadable Python scripts
 (PY files) or Jupyter notebooks (IPYNB files) that you can run. However, some
 PyAnsys libraries use the `nbsphinx <Sphinx_nbsphinx_extension_>`_ extension,
 which is specifically designed for working with and integrating Jupyter notebooks

doc/source/content-writing/py-files-writers/docstring-format-rules.rst

@@ -446,7 +446,7 @@ back to them as needed:
 - Enclose all code entities in double backticks. If you surround a code entity in only a single
   backtick (:code:`\``), it is incorrectly rendered in italics in the documentation.
 
-- Use the present tense for verbs. Occurrences of ``will`` cause `Vale <Vale_>`_ to
+- Use the present tense for verbs. Occurrences of ``will`` cause `Vale`_ to
   raise warnings about not using phrases expressing future actions.
 
 - When documenting variable length positional or keyword arguments, leave the leading single

doc/source/content-writing/rst-files-writers/cards.rst

@@ -11,8 +11,10 @@ custom cards.
 
 .. note::
    To use custom cards in your PyAnsys documentation, you must install
-   and configure the `sphinx-design <Sphinx_ext_sphinx_design_>`_
-   extension. For more information, see :ref:`add_sphinx_extensions`.
+   the `sphinx-design <Sphinx_ext_sphinx_design_>`_ extension and then
+   add it to the ``conf.py`` file in the ``doc/source`` directory and to
+   your list of documentation requirements. For more information, see
+   :ref:`add_sphinx_extensions`.
 
    To see and use the cards that are shown only as images on this page,
    click the links to their respective documentation pages. To see how these

doc/source/content-writing/rst-files-writers/collapsible-sections.rst

@@ -0,0 +1,28 @@
+.. _collapsible_sections:
+
+Collapsible sections
+====================
+
+When information is applicable only to a subset of your users or provides
+more comprehensive information than most users need, you can use collapsible
+sections. Then, only users who either need or want to view this information
+can expand these sections.
+
+.. note::
+   To use collapsible sections in your PyAnsys documentation, you must install
+   the ``sphinx_toolbox.collapse`` extension and then add it to the ``conf.py``
+   file in the ``doc/source`` directory and to your list of documentation requirements.
+   For more information, see :ref:`add_sphinx_extensions`.
+
+   To see and use the collapsible sections that are shown only as an image on this page,
+   see :ref:`artifact_download`. To see how the collapsible sections on this
+   page are formatted, click the **Show Source** link in the page's right pane.
+   As described in :ref:`rst_file_formatting`, you can copy content from the
+   TXT version of this file and then paste it directly into one of your RST files
+   for reuse, modifying it as needed.
+
+Here is an image of the three collapsible sections. Clicking a collapsible section expands it
+so that additional information is shown.
+
+.. image:: ..//_static/collapsible_sections.png
+   :alt: Collapsible sections for downloading artifacts

doc/source/content-writing/rst-files-writers/doc-links.rst

@@ -241,23 +241,29 @@ To link to Python objects in your API reference documentation, you use Python-sp
 For a list of these roles, see `Cross-referencing Python objects <Sphinx_doc_ref_Python_objects_>`_ in
 the Sphinx documentation. For descriptions of fundamental Python objects, see :ref:`py_file_format`.
 
-If the role links to a Python object in the same module, you can use only the object name
+If the role links to a Python object in the same module, you only need to use the object name
 in the role (as shown in the first of the following three examples). If the role links to a
 Python object in a different module, you must use the module name and object name in the role
 (as shown in the second and third of the following three examples).
 
 Python uses a period (``.``) to denote submodules. If you need to see where a Python object is
-defined in your documentation, use the GitHub search function. For example, to see where the
-``class Primitives3DLayout`` class is defined in PyAEDT, search its repository for this string:
+defined in your API, use the GitHub search function. For example, to see where the
+``Primitives3DLayout`` class is defined in the PyAEDT API, search its repository for this string:
 
 ``class Primitives3DLayout``
 
-Search results indicate that this class is defined in ``pyaedt.modeler.Primitives3DLayout.Primitives3DLayout``.
+Search results indicate that this class is defined here: ``pyaedt.modeler.Primitives3DLayout.Primitives3DLayout``.
+
+.. tip::
+  Because using the full module name and object name in the role always works, when you perform a
+  search to see where a Python object is defined, consider collecting the result in a TXT file. When
+  you next need to link to this object, you can easily search this text file for the object name
+  and then copy its full module name and object name into your RST file.  
 
 Examples of Python object links
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Here are some examples of how you use Python-specific roles to link to Python objects.
+Here are some examples of using Python-specific roles to link to Python objects.
 
 **Example 1**
 
@@ -273,7 +279,7 @@ Assuming that your project is PyMAPDL, you can use the ``func`` role to link to
 ``run_batch()`` function in the PyMAPDL API reference documentation::
 
   You can use the pool to run a set of pre-generated input files using the
-  :func:`run_batch <ansys.mapdl.core.LocalMapdlPool.run_batch>` method.
+  :func:`run_batch <ansys.mapdl.core.LocalMapdlPool.run_batch>` function.
 
 **Example 3**
 
@@ -282,7 +288,7 @@ Also assuming that your project is PyMAPDL, you can use both the ``func`` and
 ``selected_nodes`` attribute in the PyMAPDL API reference documentation::
 
   If you have subselected a certain component and want to also limit the result of a certain output
-  (:func:`nodal_displacement() <ansys.mapdl.core.post.PostProcessing.nodal_displacement>`), use the
+  (:func:`nodal_displacement <ansys.mapdl.core.post.PostProcessing.nodal_displacement>`), use the
   :attr:`selected_nodes <ansys.mapdl.core.post.PostProcessing.selected_nodes>` attribute to get a
   mask of the currently selected nodes.
 

doc/source/content-writing/rst-files-writers/index.rst

@@ -55,6 +55,7 @@ this **Content in RST files** section::
       tables
       cards
       tab-sets
+      collapsible-sections
 
 The ``maxdepth`` attribute of the ``toctree`` directive specifies the maximum number of
 heading levels to show in the documentation's right pane, labeled **On this page**. In this
@@ -145,3 +146,4 @@ file. However, the GitHub renderer is unaware of the ``links.rst`` file. For mor
    tables
    cards
    tab-sets
+   collapsible-sections

doc/source/content-writing/rst-files-writers/rst-format-rules.rst

@@ -83,20 +83,23 @@ page in the *Goggle developer documentation style guide*.
      * List item 4
      * List item 5
 
-- Indicate a code entity within a paragraph by surrounding it in double backticks
-  (:code:`\`\``). Always follow a code entity with a noun that indicates the object type. In the
-  documentation, a code entity is rendered in a monospaced font within a gray block.
-  (While the `numpydoc Style guide <numpydoc_style_guide_>`_ says to
-  surround a code entity in a single backtick, this renders it incorrectly in
-  italics in PyAnsys documentation.) Code entities include the names of Python
-  objects, such as packages, modules, functions, classes, instances, methods, and
-  attributes. In PyAnsys documentation, also surround the following objects
-  in double backticks:
+- Indicate a code entity within text by surrounding it in double backticks
+  (:code:`\`\``). While the `numpydoc Style guide <numpydoc_style_guide_>`_
+  says to surround a code entity in a single backtick, this renders it incorrectly
+  as italics in PyAnsys documentation. Surrounding it in double backticks
+  correctly renders it in a monospaced font within a gray block.
+
+  Always follow a code entity with a noun that indicates the object type. For general
+  guidelines, see `Code in text <Google_dev_doc_code_in_text_>`_ in the *Google developer
+  documentation style guide*. 
+
+  Code entities include the names of Python objects, such as packages, modules, functions,
+  classes, methods, and attributes. Code entities also include the following objects:
 
   - File paths
   - Names of directories, files, and environment variables
   - Text to type in a command line or in a GUI component
-
+   
   .. note::
     Some PyAnsys projects use the ``file`` and ``envvar`` interpretive text
     roles for names of files and environment variables:

doc/source/content-writing/rst-files-writers/tab-sets.rst

@@ -10,8 +10,10 @@ for different operating systems.
 
 .. note::
    To use tab sets in your PyAnsys documentation, you must install
-   and configure the `sphinx-design <Sphinx_ext_sphinx_design_>`_
-   extension. For more information, see :ref:`add_sphinx_extensions`.
+   the `sphinx-design <Sphinx_ext_sphinx_design_>`_ extension and then add
+   it to the ``conf.py`` file in the ``doc/source`` directory and to your
+   list of documentation requirements. For more information, see
+   :ref:`add_sphinx_extensions`.
 
    To see and use the tab sets that are shown only as images on this page,
    see :ref:`setting_up_dev_environment`. To see how the tab sets on this