doc/Add breadcrumb info and make general edits

README.rst

@@ -3,22 +3,22 @@ PyAnsys Sphinx Theme
 
 Introduction and Purpose
 ------------------------
-The PyAnsys documentation theme is an extension of the popular `PyData
+The PyAnsys Sphinx theme is an extension of the popular `PyData
 Sphinx Theme <https://pydata-sphinx-theme.readthedocs.io/>`_ used by
 `numpy <https://numpy.org/doc/stable/>`_, `pandas
 <https://pandas.pydata.org/docs/>`_, `PyVista
 <https://docs.pyvista.org>`_ and a variety other packages.  This theme
-was packaged a consistent documentation pattern and "feel" across the
-all PyAnsys packages.
+was packaged so that all PyAnsys packages would look and behave
+consistently. 
 
 
 Documentation
 ~~~~~~~~~~~~~
-Full documentation for the theme can found at `PyAnsys Sphinx Documentation <https://sphinxdocs.pyansys.com>`_.  The webpage was
+Full documentation can found at `PyAnsys Sphinx Theme Documentation <https://sphinxdocs.pyansys.com>`_. The webpage was
 also built using the ``pyansys-sphinx-theme``, so visit the site for a
 preview of the theme.
 
-Other Sites Using the PyAnsys theme:
+Other PyAnsys packages using the PyAnsys theme include:
 
 - `PyMAPDL <https://mapdldocs.pyansys.com/>`__
 - `PyAEDT <https://aedtdocs.pyansys.com/>`__
@@ -36,9 +36,10 @@ Install this theme with:
    pip install pyansys-sphinx-theme
 
 Next, modify your sphinx ``conf.py`` to use ``html_theme =
-'pyansys_sphinx_theme'``.  If you are just getting started using
-sphinx, follow the directions at `Sphinx Quickstart
-<https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
+'pyansys_sphinx_theme'``.  If you are new to using
+Sphinx, see `Sphinx Getting Started
+<https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_
+documentation.
 
-For further details, visit `PyAnsys Sphinx Theme Usage
+For usage information, seee `Using this Theme
 <https://sphinxdocs.pyansys.com/usage.html>`_

doc/source/class_documentation.rst

@@ -7,7 +7,7 @@ User Guide Documentation Method
 
 There are two main ways of documenting a class using Sphinx.  The
 first approach is to detail its usage via a "User Guide", or manually
-created example designed to be read within documentation.  This
+created example designed to be read within documentation. This
 approach works when demonstrating the usage of a class.  For example,
 using the ``.. code:: python`` directive:
 
@@ -38,7 +38,7 @@ parameters are automatically assigned to the class.
 Autoclass Directive
 ~~~~~~~~~~~~~~~~~~~
 
-The "user guide" approach works for explaining the "why" and "how" of a class.  As
+The "User Guide" approach works for explaining the "why" and "how" of a class.  As
 for the "what" of a class, you can describe the API automatically
 using the ``autoclass`` directive:
 
@@ -57,8 +57,8 @@ using the ``autoclass`` directive:
 Autosummary Directive
 ~~~~~~~~~~~~~~~~~~~~~
 Simple classes can be easily represented using the ``autoclass``
-directive, but more complex classes with many methods should be
-documented via the ``autosummary`` directive.  For example,
+directive. However, more complex classes with many methods should be
+documented via the ``autosummary`` directive.  For example:
 
 .. code::
 
@@ -68,7 +68,7 @@ documented via the ``autosummary`` directive.  For example,
       pyansys_sphinx_theme.samples.Complex
 
 
-Will generate the following documentation:
+This code will generate the following documentation:
 
 .. autosummary::
    :toctree: _autosummary

doc/source/coding_style.rst

@@ -23,7 +23,7 @@ Aside from pyansys specific directives, the best coding practice is to simply
 follow established guidelines from `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
 
 
-Deprecation Best-Practice
+Deprecation Best Practice
 -------------------------
 Whenever a method, class, or function is deprecated, we must provide
 an old method that calls the new method and raises a warning, or raise
@@ -108,11 +108,11 @@ Then simply use that inplace of ``Exception``
         """
         raise DeprecationError('`my_function` has been deprecated')
 
-Imports Best-Practice
+Imports Best Practice
 ---------------------
 
 Following the `PEP8 guidelines <https://www.python.org/dev/peps/pep-0008/#imports>`_,
-imports should be added at the top of the file and should be grouped in the following order:
+imports should be added at the top of the file and should be grouped in this order:
 
 1. Standard library imports.
 2. Related third party imports.
@@ -136,7 +136,7 @@ For example, consider the unorganized imports below:
     from ansys.mapdl.core.commands import Commands
     from ansys.mapdl.core.inline_functions import Query
 
-Organizing those same imports into groups vastly improves readibilty:
+Organizing these same imports into groups vastly improves readibilty:
 
 .. code:: python
 
@@ -156,9 +156,9 @@ Organizing those same imports into groups vastly improves readibilty:
     from ansys.mapdl.core.commands import Commands
     from ansys.mapdl.core.inline_functions import Query
 
-It is also recommended that the imports within a section be organized alphabetically.
-Following this convention makes imports easily searchable. This standard is optional 
-and will not be enforced, but it may be preferred in some projects.
+We also recommend that the imports within a section be organized alphabetically.
+Following this convention makes imports easily searchable. While this standard is optional,
+it may be preferred in some projects.
 
 .. code:: python
 
@@ -178,7 +178,7 @@ and will not be enforced, but it may be preferred in some projects.
     from ansys.mapdl.core.plotting import general_plotter
     from ansys.mapdl.core.post import PostProcessing
 
-Additionally, it is recommended to use absolute imports over relative imports, since they are 
+Additionally, we recommend to use absolute imports over relative imports because they are 
 more readable and reliable:
 
 .. code:: python
@@ -201,7 +201,7 @@ method or feature is added, changed, or removed, the minor version
 should be bumped.
 
 To avoid constantly bumping the minor version, one approach to for
-source-control branching is to create release branches where only
+source control branching is to create release branches where only
 patch fixes are pushed to, and API changes occur between minor
 releases.  See `Trunk Based Development
 <https://trunkbaseddevelopment.com/>`_.  In summary, the mainline
@@ -218,7 +218,7 @@ update any projects dependent on the API while still being treated as
 multiple "release branches" in a repository, the number of active
 release branches should be between one and three.
 
-Docstring Examples Best-Practice
+Docstring Examples Best Practice
 --------------------------------
 Defining docstring examples for methods and classes are extremely 
 useful. The examples give users an easy place to start when trying 
@@ -228,7 +228,7 @@ also be used to perform regression testing to verify that the code is
 executing as expected.
 
 This is an important feature of maintainable documentation as examples
-must always match the API they are documenting, and any changes within
+must always match the API that they are documenting. Any changes within
 the API without a corresponding change in the documentation will
 trigger doctest failures.
 
@@ -252,11 +252,11 @@ execute them to verify that they function as written.
 Using ``pytest`` Fixtures
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 To define a setup sequence before the ``doctest`` run or before a given 
-module is tested, ``pytest`` fixtures can be used. Fixtures allow docstring 
-examples to access shared objects, so there is no need to repeat the setup
+module is tested, you can use ``pytest`` fixtures. Because fixtures allow docstring 
+examples to access shared objects, there is no need to repeat the setup
 in each example.
 
-``pytest`` fixtures can defined in a ``conftest.py`` file next to the source 
+You can define ``pytest`` fixtures in a ``conftest.py`` file next to the source 
 code. The following example shows a fixture that is run automatically for 
 each ``doctest`` session.
 
@@ -276,7 +276,7 @@ each ``doctest`` session.
         yield desktop
         desktop.force_close_desktop()
 
-Fixtures can also be defined in a separate Python file from 
+You can also define fixtures in a separate Python file from 
 ``conftest.py``. This may help keep the fixtures more organized. Fixtures 
 from other files need to be imported in the main ``conftest.py`` file. The 
 following example shows how to import fixtures defined in an 
@@ -345,7 +345,7 @@ example, by referencing the key ``icepak``.
         Examples
         --------
 
-        Create an opening boundary for the faces of the "USB_GND" object.
+        Create an opening boundary for the faces of the ``USB_GND`` object.
 
         >>> faces = icepak.modeler.primitives["USB_GND"].faces
         >>> face_names = [face.id for face in faces]
@@ -358,7 +358,7 @@ example, by referencing the key ``icepak``.
 Useful Features
 ~~~~~~~~~~~~~~~
 
-Ellipses For Random Output
+Ellipses for Random Output
 **************************
 If the output of some operation in an example cannot be verified exactly,
 an ellipsis (``...``) can be used in the expected output. This allows it

doc/source/usage.rst

@@ -8,28 +8,28 @@ Install this theme with:
 
    pip install pyansys-sphinx-theme
 
-If you are just getting started using sphinx, follow the directions at
-`Sphinx Quickstart
-<https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.  Next,
-modify your sphinx ``conf.py`` to use ``html_theme =
-'pyansys_sphinx_theme'``.  Consider using the following ``conf.py`` used in this repository:
+If you are are new to Sphinx, see the
+`Sphinx Getting Started
+<https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_ documentation.
+Next, modify your Sphinx ``conf.py`` file to use ``html_theme =
+'pyansys_sphinx_theme'``. Consider using the following ``conf.py`` for this repository:
 
 .. literalinclude:: ./conf.py
    :language: python
 
 
-For additional configuration options, see `Configuring The PyData
-Sphinx Theme
-<https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html>`_,
-which forms the basis for the style of this theme.
+For additional configuration options, see the `Configuration
+<https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html>`_
+topic for the PyData Sphinx theme, which is the basis for the style of this 
+PyAnsys theme.
 
 
 Editing the CSS
 ~~~~~~~~~~~~~~~
 
-If you need to edit or append to the css, create a directory next to
-your ``conf.py`` named ``_static/css`` containing your ``custom.css``
-file.  For example:
+If you need to edit or append to the css, create a directory named ``_static/css``
+next to your ``conf.py`` file . Create your ``custom.css`` file in this directory.
+For example:
 
 .. code::
 
@@ -47,11 +47,30 @@ file.  For example:
    .prev-next-bottom{margin-bottom: 6rem}
 
 
-Next, add the following to ``conf.py``:
+Next, add the following to your ``conf.py`` file:
 
 .. code:: python
 
     html_static_path = ['_static']
     html_css_files = ['css/custom.css']
 
-This way you can override the CSS style of this theme.
+Use your ``custom.css`` file to override the CSS style of this theme.
+
+Adding Breadcrumbs
+~~~~~~~~~~~~~~~~~~
+The PyAnsys Sphinx theme supports the display of breadcrumbs on
+the body of documentation pages to make navigation easier. These 
+breadcrumbs are disabled by default. To add
+breadcrumbs to the pages of your documentation, in the ``conf.py``
+file, add ``"show_breadcrumbs": True`` to the ``html_theme_options`` dictionary.
+
+If you want to add additional 'root' breadcrumbs, such as to the 
+PyAnsys Documentation homepage, add them to the ``html_theme_options`` dictionary as a list of tuples
+with the ``"additional_breadcrumbs"`` key. The tuples are of the form ``("Link text", "url")``.
+
+When on the module homepage, a breadcrumb will be displayed with the homepage title.
+However, this title is not accessible to Sphinx from other documentation pages. Therefore, the ``html_short_title``
+is used as the display text for the documentation homepage breadcrumb. To ensure a consistent user experience
+you should ensure the ``html_short_title`` (or optionally ``html_title`` if ``html_short_title`` is not used)
+is set to the same value as the title of the ``index.rst`` page. If you want to use the version number
+in the ``index.rst`` title, use ``|version|`` to include the package version number.