Collect common links under custom file

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,26 +1,16 @@
-.. _style-guide-enforcement:
-
 Style Guide Enforcement
 =======================
-This topic describes the use of `Flake8`_ for `PEP8`_ style
+This topic describes the use of `flake8`_ for `PEP 8`_ style
 enforcement and the minimum standards expected. PyAnsys libraries
 are expected to be consistent with these guidelines.
 
-.. _PEP8: https://www.python.org/dev/peps/pep-0008/
-
 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: https://flake8.pycqa.org/en/latest/index.html
-.. _PyFlakes: https://pypi.org/project/pyflakes/
-.. _pycodestyle: https://pypi.org/project/pycodestyle/
-.. _`Ned Batchelder's McCabe script for complexity`: https://github.com/PyCQA/mccabe
-.. _configuring-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`, 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
 ------------------
@@ -44,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:
 
@@ -59,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.
@@ -70,7 +59,7 @@ The example configuration defines the following options:
 
 - ``max-line-length``
     Denotes the maximum line length for any one line of code.
-    The `PEP8`_ standard advises a maximum line length of 79. Because
+    The `PEP 8`_ standard advises a maximum line length of 79. Because
     this is a bit limiting in some cases, the maximum line length
     recommended for a PyAnsys library is 100.
 
@@ -106,25 +95,21 @@ base.
 Utilizing Black
 ~~~~~~~~~~~~~~~
 Manually checking for code styling can be a tedious task. Luckily,
-several Python tools for auto-formatting code to meet PEP8 standards
+several Python tools for auto-formatting code to meet `PEP 8`_ standards
 are available to help with this. The PyAnsys project suggests the use of the
 the formatting tool `black`_.
 
 On completing a code change, and before committing, `black`_ can be
-run to reformat the code, following the PEP8 guidelines enforced through
-Flake8. This will limit any manual code changes needed to address style
+run to reformat the code, following the `PEP 8`_ guidelines enforced through
+`flake8`_. This will limit any manual code changes needed to address style
 rules.
 
-.. _black: https://black.readthedocs.io/en/stable/
 
 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
-PEP8 guidelines requires minimal manual effort.
-
-.. _pre-commit: https://pre-commit.com/
+`PEP 8`_ guidelines requires minimal manual effort.
 
 
 Minimum Standards
@@ -194,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.**
 
@@ -215,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.
 
@@ -233,20 +217,8 @@ Your ``.flake8`` file should be:
     statistics = True
 
 
-.. _W191: https://www.flake8rules.com/rules/W191.html
-.. _W291: https://www.flake8rules.com/rules/W291.html
-.. _W293: https://www.flake8rules.com/rules/W293.html
-.. _W391: https://www.flake8rules.com/rules/W391.html
-.. _E115: https://www.flake8rules.com/rules/E115.html
-.. _E117: https://www.flake8rules.com/rules/E117.html
-.. _E122: https://www.flake8rules.com/rules/E122.html
-.. _E124: https://www.flake8rules.com/rules/E124.html
-.. _E125: https://www.flake8rules.com/rules/E125.html
-.. _E225: https://www.flake8rules.com/rules/E225.html
-.. _E231: https://www.flake8rules.com/rules/E231.html
-.. _E301: https://www.flake8rules.com/rules/E301.html
-.. _E303: https://www.flake8rules.com/rules/E303.html
-.. _E501: https://www.flake8rules.com/rules/E501.html
-.. _F401: https://www.flake8rules.com/rules/F401.html
-.. _F403: https://www.flake8rules.com/rules/F403.html
-
+.. 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,17 +1,10 @@
-.. _coding_style:
-
 Coding Style
-************
+############
 
-PyAnsys libraries are expected to follow `PEP8`_ and
+PyAnsys libraries are expected to follow `PEP 8`_ and
 be consistent in style and formatting with the 'big three'
 data science libraries: `NumPy`_, `SciPy`_, and `pandas`_.
 
-.. _NumPy: https://numpy.org/
-.. _SciPy: https://www.scipy.org/
-.. _pandas: https://pandas.pydata.org/
-.. _PEP8: https://www.python.org/dev/peps/pep-0008/
-
 
 .. todo::
 
@@ -27,3 +20,5 @@ data science libraries: `NumPy`_, `SciPy`_, and `pandas`_.
    pep8_best_practices
    beyond_pep8
    flake8
+
+.. include:: ../links.rst