Doc/fix minor formatting and style issues (#443)

* Minor fixes

* Minor fixes based on skimming rendered doc

* Additional edits

* Fix Vale issues

* Resolve doc build errors

* Edit to add-sphinx-extensions

* Resolve link issues causing doc build failure

* Fix mistake

* Apply suggestions from code review

Add corrections for mistakes found by Roberto and Revathy

Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com>
Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com>

---------

Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com>
Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com>

Author: 3 people

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/_static/collapsible_sections.png

@@ -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/add-sphinx-extensions.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/resolve-issues-causing-check-failures.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/view-revision-history.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/content-how-tos/work-around-Vale.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/examples-writers/index.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