Fix links and cross-references

Author: jorgepiloto

doc/source/abstractions/app-interface.rst

@@ -106,8 +106,9 @@ the model setup object.  There's no reason why a user needs direct
 access to ``_omodelsetup``, which is why it's protected in the
 ``Hfss`` class. Additionally, calling the method is simplified by
 providing (and documenting) the defaults using keyword arguments and
-placing them into the ``vars`` list, all while following the `Style
-Guide for Python Code (PEP8)`_.
+placing them into the ``vars`` list, all while following the Style
+Guide for Python Code, defined in `PEP 8`_.
 
-.. _PyAEDT: https://github.com/pyansys/pyaedt
-.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008
+
+.. LINKS AND REFERENCES
+.. include:: ../links.rst

doc/source/abstractions/data-transfer.rst

@@ -3,10 +3,10 @@ Data Transfer
 
 Abstracted APIs should attempt to hide the implementation details of
 the remote or local API in a well organized data model.  This data
-model should avoid returning raw JSON files, gRPC messages, SWIG objects,
+model should avoid returning raw JSON files, gRPC messages, `SWIG`_ objects,
 or .NET objects. It should preferably return standard Python objects
-like lists, strings, dictionaries when useful, and `NumPy <https://numpy.org/>`_
-arrays or `pandas <https://pandas.pydata.org/>`_ dataframes for more complex data.
+like lists, strings, dictionaries when useful, and `NumPy`_
+arrays or `pandas`_ dataframes for more complex data.
 
 For example, consider a simple mesh in MAPDL:
 
@@ -109,16 +109,5 @@ interface that can efficiently exchange a wide variety of data formats and
 messages.
 
 
-.. _gRPC: https://grpc.io/
-.. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html
-.. _SWIG: http://www.swig.org/
-.. _C extensions: https://docs.python.org/3/extending/extending.html
-.. _Anaconda Distribution: https://www.anaconda.com/products/individual
-.. _REST: https://en.wikipedia.org/wiki/Representational_state_transfer
-.. _PyAEDT: https://github.com/pyansys/PyAEDT
-.. _PyMAPDL: https://github.com/pyansys/pymapdl
-.. _pymapdl: https://github.com/pyansys/pymapdl
-.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008
-.. _grpc_chunk_stream_demo: https://github.com/pyansys/grpc_chunk_stream_demo
-.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
-.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/
+.. LINKS AND REFERENCES
+.. include:: ../links.rst

doc/source/abstractions/service.rst

@@ -10,12 +10,11 @@ the "desktop API". In this case, remote API calls should be identical
 if the service is local or remote, with the only difference being that local
 calls are faster to execute.
 
-Consider the following code examples. The left-hand side shows the
-amount of work to start, establish a connection to, and submit an
-input file to MAPDL using auto-generated gRPC interface files. For
-more information, see `pyansys-protos-generator
-<https://github.com/pyansys/pyansys-protos-generator>`_.  The 
-right-hand side shows the same workflow but uses the `PyMAPDL`_ library.
+Consider the following code examples. The left-hand side shows the amount of
+work to start, establish a connection to, and submit an input file to MAPDL
+using auto-generated gRPC interface files. For more information, see
+`pyansys-protos-generator`_. The right-hand side shows the same workflow but
+uses the `PyMAPDL`_ library.
 
 +----------------------------------------------------------+--------------------------------------------+
 | Using the gRPC Auto-generated Interface                  | Using the `PyMAPDL`_ Library               |
@@ -78,6 +77,5 @@ At this point, because the assumption is that MAPDL is always remote, it's
 possible to issue commands to MAPDL, including those requiring 
 file transfer like ``Mapdl.input``.
 
-.. _REST: https://en.wikipedia.org/wiki/Representational_state_transfer
-.. _gRPC: https://grpc.io/
-.. _PyMAPDL: https://github.com/pyansys/pymapdl
+.. LINKS AND REFERENCES
+.. include:: ../links.rst

doc/source/coding_style/beyond_pep8.rst

@@ -1,15 +1,15 @@
 Beyond PEP8
-###########
+===========
 This topic describes any delineations, clarifications, or additional procedures above and 
-beyond `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
+beyond `PEP 8`_.
 
-For example, `Stack Overflow Answer <https://stackoverflow.com/questions/2536307>`_ 
-outlines deprecation best practices and a `Deprecation library <https://deprecation.readthedocs.io/>`_ 
-already exists. However, there is no official guidance regarding deprecating features 
-in an API within Python. This page seeks to clarify this issue and others.
+For example, `Stack Overflow Answer`_ outlines deprecation best practices and a
+`Deprecation`_ library already exists. However, there is no official guidance
+regarding deprecating features in an API within Python. This page seeks to
+clarify this issue and others.
 
 Aside from the following PyAnsys-specific directives, the best coding practice is to 
-follow established guidelines from `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
+follow established guidelines from `PEP 8`_.
 
 
 Deprecation Best Practice
@@ -18,8 +18,7 @@ Whenever a method, class, or function is deprecated, you must provide
 an old method that both calls the new method and raises a warning. Or, 
 if the method has been removed, you must raise an ``AttributeError``. 
 
-In the docstring of the older method, provide a `Sphinx Deprecated Directive
-<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated>`_ 
+In the docstring of the older method, provide a `Sphinx Deprecated Directive`_
 and a link to the newer method. This way, users are notified that an API change 
 has occurred and are given an opportunity to change their code. Otherwise, 
 stability concerns can cause users to stop upgrading, or worse, stop using 
@@ -50,7 +49,7 @@ an error after a minor release or two.
             raise AttributeError('assignmaterial is deprecated. Use assign_material instead.')
 
         def assign_material(self, obj, mat):
-            """Assign a material to one or more objects.
+            """Assign a material to one or more objects."""
             ...
 
 
@@ -99,7 +98,7 @@ You can then use this custom ``DeprecationError`` in place of an ``Exception``.
 
 Semantic Versioning and API Changes
 -----------------------------------
-According to `Semantic Versioning <https://semver.org/>`_, you should
+According to `Semantic Versioning`, you should
 increment the MAJOR version when you make incompatible changes.
 However, adding or eliminating methods should not be considered
 incompatible changes to a code base but rather incremental changes
@@ -110,8 +109,7 @@ should be bumped.
 To avoid constantly bumping the minor version, one approach to 
 source-control branching is to create release branches where only
 patch fixes are pushed and API changes occur between minor
-releases. See `Trunk Based Development
-<https://trunkbaseddevelopment.com/>`_.  
+releases. See `Trunk Based Development`_.
 
 In summary, the mainline branch (commonly named ``main`` or ``master``) 
 must always be ready to release, and developers should create 
@@ -275,7 +273,7 @@ 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
 to match any substring in the actual output.
 
-.. code ::
+.. code::
 
     Examples
     --------
@@ -286,7 +284,7 @@ to match any substring in the actual output.
 
 To support this, ``doctest`` must be run with the option set to allow ellipses.
 
-.. code ::
+.. code::
 
     pytest --doctest-modules -o ELLIPSIS file.py
 
@@ -298,9 +296,15 @@ This is useful for examples that cannot run within ``pytest`` or have
 side effects that will affect the other tests if they are run during 
 the ``doctest`` session.
 
-.. code :: python
+.. code:: python
 
     Examples
     --------
 
     >>> desktop = Desktop("2021.1") # doctest: +SKIP
+
+
+.. LINKS AND REFERENCES
+.. include:: ../links.rst
+.. _Sphinx Deprecated Directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated
+.. _Stack Overflow Answer: htps://stackoverflow.com/questions/2536307

doc/source/coding_style/flake8.rst

@@ -1,5 +1,3 @@
-.. _style-guide-enforcement:
-
 Style Guide Enforcement
 =======================
 This topic describes the use of `flake8`_ for `PEP 8`_ style
@@ -8,11 +6,11 @@ are expected to be consistent with these guidelines.
 
 Flake8
 ~~~~~~
-`flake8`_ is a Python tool for enforcing code styling. It is a wrapper
-around the following three tools: `PyFlakes`_, `pycodestyle`_, and
-`Ned Batchelder's McCabe script for complexity`_. Flake8 runs all three tools at once,
-checking the code against a variety of style rules, such as line length,
-code complexity, and whitespace.
+`Flake8`_ is a Python tool for enforcing code styling. It is a wrapper around
+the following three tools: `PyFlakes`_, `pycodestyle`_, and `Ned Batchelder's
+McCabe script for complexity`, also known as `mccabe`_. Flake8 runs all three
+tools at once, checking the code against a variety of style rules, such as line
+length, code complexity, and whitespace.
 
 Configuring Flake8
 ------------------
@@ -36,8 +34,7 @@ library:
     statistics = True
 
 Flake8 has many options that can be set within the configuration file.
-For a list and descriptions, see this `Flake8 documentation topic
-<https://flake8.pycqa.org/en/latest/user/options.html>`__.
+For a list and descriptions, see this `Flake8 documentation topic`_.
 
 The example configuration defines the following options:
 
@@ -51,7 +48,7 @@ The example configuration defines the following options:
     check for and is not an exhaustive list.
 
     For a full list of error codes and their descriptions, see this `Flake8
-    documentation topic <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html>`__.
+    documentation topic`_
 
 - ``count``
     Total number of errors to print at the end of the check.
@@ -109,8 +106,7 @@ rules.
 
 
 Optionally, it is possible to automate the use of `black`_. This can be
-done with the tool `pre-commit`_. Setting up a `pre-commit hook
-to run black <https://black.readthedocs.io/en/stable/integrations/source_version_control.html>`_
+done with the tool `pre-commit`_. Setting up a `pre-commit hook to run black`_
 will automatically format the code before committing. This simple way of
 incorporating code style checks into the development workflow to maintain
 `PEP 8`_ guidelines requires minimal manual effort.
@@ -183,12 +179,11 @@ expected in a PyAnsys library.
 
 * `E501`_ - **Line too long.**
 
-    All code lines should not exceed 100 characters. The
-    `PEP8 line length guideline <https://www.python.org/dev/peps/pep-0008/#maximum-line-length>`_
-    suggests a maximum line length of 79. Following this limit
-    is not as necessary today due to modern screen sizes. The suggested maximum
-    length of 100 can be easier to accommodate and can still support
-    viewing files side by side in code editors.
+    All code lines should not exceed 100 characters. The `PEP8 line length
+    guideline`_ suggests a maximum line length of 79. Following this limit is
+    not as necessary today due to modern screen sizes. The suggested maximum
+    length of 100 can be easier to accommodate and can still support viewing
+    files side by side in code editors.
 
 * `F401`_ - **Module imported but unused.**
 
@@ -204,7 +199,7 @@ expected in a PyAnsys library.
 * **Limit complexity of code to 10.**
 
   This is enforced by the ``max-complexity`` option described in
-  :ref:`configuring-flake8`. Limiting code complexity leads to code that
+  :ref:`PEP 8 Best Practices`. Limiting code complexity leads to code that
   is easier to understand and less risky to modify. Write low-
   complexity code when possible.
 
@@ -221,4 +216,9 @@ Your ``.flake8`` file should be:
     max-line-length = 100
     statistics = True
 
+
+.. REFERENCES AND LIKNS
 .. include:: ../links.rst
+.. _Flake8 documentation topic: https://flake8.pycqa.org/en/3.9.2/user/error-codes.html
+.. _PEP8 line length guideline: https://www.python.org/dev/peps/pep-0008/#maximum-line-length
+.. _pre-commit hook to run black: https://black.readthedocs.io/en/stable/integrations/source_version_control.html

doc/source/coding_style/index.rst

@@ -1,5 +1,5 @@
 Coding Style
-************
+############
 
 PyAnsys libraries are expected to follow `PEP 8`_ and
 be consistent in style and formatting with the 'big three'

doc/source/coding_style/pep8_best_practices.rst

@@ -1,8 +1,6 @@
-.. _best_practices:
-
 PEP 8 Best Practices
 ====================
-This topic summarizes key points from `PEP8`_ and how
+This topic summarizes key points from `PEP 8`_ and how
 they apply to PyAnsys libraries. The goal is for PyAnsys libraries to
 be consistent in style and formatting with the `big three`
 data science libraries: `NumPy`_, `SciPy`_, and `pandas`_.
@@ -15,8 +13,6 @@ module comments and docstrings and before module globals and
 constants.  This reduces the likelihood of an `ImportError`_ that
 might only be discovered during runtime.
 
-.. _ImportError: https://docs.python.org/3/library/exceptions.html#ImportError
-
 Instead of:
 
 .. code:: python
@@ -95,7 +91,7 @@ Use:
 
 You should avoid using wild cards in imports because doing so
 can make it difficult to detect undefined names.  For more information,
-see `Python Anti-Patterns: using wildcard imports <(https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html>`_.
+see `Python Anti-Patterns: using wildcard imports`_.
 
 Instead of:
 
@@ -259,7 +255,7 @@ from PyPi.
 
 Class Naming Conventions
 ~~~~~~~~~~~~~~~~~~~~~~~~
-Use `camel case <https://en.wikipedia.org/wiki/Camel_case>`_ when naming classes. Do not separate words
+Use `camel case`_ when naming classes. Do not separate words
 with underscores. 
 
 .. code:: python
@@ -433,21 +429,17 @@ same line:
 
 For a multi-line docstring, put the ending ``"""`` on a line by itself.
 
-PyAEDT follows the `numpydoc
-<https://numpydoc.readthedocs.io/en/latest/format.html>`_
-docstring style, which is used by `numpy <https://numpy.org/>`_,
-`scipy <https://www.scipy.org/>`_, `pandas
-<https://pandas.pydata.org/>`_, and a variety of other Python open
-source projects.  For more information on docstrings for PyAnsys
-libraries, see :ref:`api_documentation`.
+`PyAEDT`_ follows the `numpydoc`_ docstring style, which is used by `numpy`_
+`scipy`_, `pandas`_, and a variety of other Python open source projects.  For
+more information on docstrings for PyAnsys libraries, see
+:ref:`API Documentation Style`.
 
 
 Programming Recommendations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The following sections provide some `PEP8
-<https://www.python.org/dev/peps/pep-0008/>`_ suggestions for removing
-ambiguity and preserving consistency. They address some common pitfalls 
-when writing Python code.
+The following sections provide some `PEP 8`_ suggestions for removing ambiguity
+and preserving consistency. They address some common pitfalls when writing
+Python code.
 
 
 Booleans and Comparisons
@@ -714,6 +706,13 @@ Any library should be secure and implement good practices that avoid or mitigate
 This is especially relevant in libraries that request user input (such as web services).
 Because security is a broad topic, we recommend you review this useful Python-specific resource:
 
-* `10 Unknown Security Pitfalls for Python <https://blog.sonarsource.com/10-unknown-security-pitfalls-for-python>`_ - By Dennis Brinkrolf - Sonar source blog
+* `10 Unknown Security Pitfalls for Python`_ - By Dennis Brinkrolf - Sonar source blog
 
-.. [#] Wikipedia - `Software development security <https://en.wikipedia.org/wiki/Software_development_security>`_. 
+
+.. LINKS AND REFERENCES
+.. include:: ../links.rst
+.. [#] Wikipedia - Software development security https://en.wikipedia.org/wiki/Software_development_security
+.. _10 Unknown Security Pitfalls for Python: https://blog.sonarsource.com/10-unknown-security-pitfalls-for-python
+.. _camel case: https://en.wikipedia.org/wiki/Camel_case
+.. _ImportError: https://docs.python.org/3/library/exceptions.html#ImportError
+.. _Python Anti-Patterns\: using wildcard imports: https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html

doc/source/documentation_style/deployment.rst

@@ -1,14 +1,13 @@
-.. _documentation_deployment:
-
-
 Documentation Deployment
 ------------------------
-Documentation for the PyAnsys project is hosted via `GitHub Pages <https://pages.github.com/>`_. 
-Given the open-source nature of the project, documentation built by each PyAnsys library or
-project should be public and editable by users and the community at large.
 
-After following the documentation build strategy contained within both
-the `pyansys/template <https://github.com/pyansys/template/>`_ and
-`pyansys-sphinx-theme
-<https://github.com/pyansys/pyansys-sphinx-theme>`_ you will end up
-with html documentation files in ``doc/build/html``.  
+Documentation for the PyAnsys project is hosted via `GitHub Pages`_ Given the
+open-source nature of the project, documentation built by each PyAnsys library
+or project should be public and editable by users and the community at large.
+
+After following the documentation build strategy contained within both the
+`ansys-templates`_ and `pyansys-sphinx-theme`_ you will end up with html
+documentation files in ``doc/build/html``.  
+
+.. Links and References
+.. include:: ../links.rst