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/guidelines/dev_practices.rst

@@ -1,17 +1,15 @@
-.. _development_practices:
-
 Development Practices
 =====================
 This page explains how PyAnsys development is conducted. When
 contributing to a PyAnsys repository, use these general
 coding paradigms:
 
-#. Follow the `Zen of Python <https://www.python.org/dev/peps/pep-0020/>`__.
+#. Follow the `Zen of Python <https://www.python.org/dev/peps/pep-0020/>`_.
    As silly as core Python developers are sometimes, there's much to be
    gained by following the basic guidelines listed in PEP 20. As suggested
    in these guidelines, focus on making your additions intuitive, novel,
    and helpful for PyAnsys users. When in doubt, use ``import this``.
-   For Ansys code quality standards, see :ref:`coding_style`.
+   For Ansys code quality standards, see :ref:`Coding Style`.
 
 #. Document your contributions. Include a docstring for any added
    function, method, or class, following `numpydocs docstring <https://numpydoc.readthedocs.io/en/latest/format.html>`_

doc/source/links.rst

@@ -4,7 +4,10 @@
 .. PYANSYS PROJECTS
 .. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/
 .. _ansys-templates: https://templates.pyansys.com/index.html
+.. _pyansys-protos-generator: https://github.com/pyansys/pyansys-protos-generator
+.. _grpc_chunk_stream_demo: https://github.com/pyansys/grpc_chunk_stream_demo
 .. _PyAEDT: https://github.com/pyansys/pyaedt
+.. _PyMAPDL: https://github.com/pyansys/pymapdl
 .. _PyAnsys: https://docs.pyansys.com/
 .. _PyAnsys PyPI: https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi
 .. _PyAnsys GitHub Organization: https://github.com/pyansys
@@ -17,6 +20,7 @@
 .. CODE FORMATTING AND QUALITY TOOLS
 .. _black: https://black.readthedocs.io/en/stable/
 .. _flake8: https://flake8.pycqa.org/en/latest/index.html
+.. _pre-commit: https://pre-commit.com/
 .. _pycodestyle: https://pypi.org/project/pycodestyle/
 .. _pyflakes: https://pypi.org/project/pyflakes/
 
@@ -33,11 +37,43 @@
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _sphinx-gallery: https://sphinx-gallery.github.io/
 
-.. PYTHON ECOSYSTEM
+.. FLAKE8 RULE CODES
+.. _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
+.. _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
+
+.. GIT
+.. _Semantic Versioning: https://semver.org/
+.. _Trunk Based Development: https://trunkbaseddevelopment.com/  
+  
+
+.. LICENSES
+.. _MIT License: https://opensource.org/licenses/MIT
+
+.. PYTHON ECOSYSTEM AND LIBRARIES
 .. _Python Packaging Authority: https://www.pypa.io/en/latest/
 .. _Python Packaging User Guide: https://packaging.python.org/en/latest/
 .. _pip: https://pip.pypa.io/en/latest/
 
+.. THIRD PARTY LIBRARIES
+.. _deprecation: https://deprecation.readthedocs.io/en/latest/
+.. _numpy: https://numpy.org/
+.. _pandas: https://pandas.pydata.org/
+.. _scipy: https://scipy.org/
+
 .. PYTHON ENHANCEMENT PROPOSAL (PEP) LINKS
 .. _PEP 8: https://peps.python.org/pep-0008/
 .. _PEP 20: https://peps.python.org/pep-0020/
@@ -46,30 +82,17 @@
 .. _PEP 517: https://peps.python.org/pep-0517/
 .. _PEP 518:  https://peps.python.org/pep-0518/
 
+.. COMMON TECHNOLOGIES
+.. _gRPC: https://grpc.io/
+.. _rest: https://en.wikipedia.org/wiki/Representational_state_transfer
+.. _SWIG: http://www.swig.org/
+
 .. UNIT TESTING AND CI TOOLS
 .. _codecov.io: https://app.codecov.io/gh/pyansys
 .. _dependabot: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates
 .. _GitHub Actions: https://github.com/features/actions
 .. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository
 .. _pytest: https://docs.pytest.org/en/latest/
 .. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
-.. _Test driven development: https://en.wikipedia.org/wiki/Test-driven_development
+.. _Test Driven Development: https://en.wikipedia.org/wiki/Test-driven_development
 .. _Tox: https://tox.wiki/en/latest/
-
-.. FLAKE8 RULE CODES
-.. _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
-.. _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