Docs/content writing

.github/workflows/ci_cd.yml

@@ -38,7 +38,6 @@ jobs:
 
   doc-build:
     name: "Build project documentation"
-    needs: doc-style
     runs-on: ubuntu-latest
     steps:
       - name: "Install mermaid-cli"
@@ -137,7 +136,7 @@ jobs:
           documentation-pdf
 
   doc-deploy-github-release:
-    name: "Deploy documentation"
+    name: "Deploy documentation (stable)"
     runs-on: ubuntu-latest
     needs: [release-github]
     steps:

doc/.vale.ini

@@ -26,10 +26,11 @@ Vocab = ANSYS
 
 # Apply the following styles
 BasedOnStyles = Vale, Google
+Vale.Terms = NO
 
 # Inline roles are ignored
 TokenIgnores = (:.*:`.*`)
 
 # Removing Google-specific rule - Not applicable under some circumstances
 Google.WordList = NO
-Google.Colons = NO
+Google.Colons = NO

doc/source/abstractions/app-interface.rst

@@ -112,6 +112,3 @@ access to ``_omodelsetup``, which is why it's protected in the
 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)`_.
-
-.. _PyAEDT: https://github.com/ansys/pyaedt
-.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008

doc/source/abstractions/data-transfer.rst

@@ -5,8 +5,8 @@ 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,
 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:
 
@@ -110,18 +110,3 @@ benefits of a binary compatible protocol. While REST provides a variety of
 benefits, for complex client/server interactions, it is best to have an
 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/ansys/PyAEDT
-.. _PyMAPDL: https://github.com/ansys/pymapdl
-.. _pymapdl: https://github.com/ansys/pymapdl
-.. _Style Guide for Python Code (PEP8): https://www.python.org/dev/peps/pep-0008
-.. _grpc_chunk_stream_demo: https://github.com/ansys/grpc_chunk_stream_demo
-.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
-.. _Namespace Packages: https://packaging.python.org/guides/packaging-namespace-packages/

doc/source/abstractions/service.rst

@@ -15,7 +15,7 @@ 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/ansys/pyansys-protos-generator>`_.  The 
-right-hand side shows the same workflow but uses the `PyMAPDL`_ library.
+right-hand side shows the same workflow but uses `PyMAPDL`_.
 
 +----------------------------------------------------------+--------------------------------------------+
 | Using the gRPC Auto-generated Interface                  | Using the `PyMAPDL`_ Library               |
@@ -78,7 +78,3 @@ of MAPDL via gRPC by instantiating an instance of the ``Mapdl`` class.
 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/ansys/pymapdl

doc/source/all-styles.rst

@@ -7,8 +7,8 @@ enhanced developer experience: packaging style, coding style, and documentation
 
 - Packaging style focuses on creating clear, open source APIs hosted on GitHub,allowing
   for reusable packages that can be updated independently of the Ansys release schedule.
-- Coding style adheres to PEP 8 and aligns with the conventions of major data science libraries
-  like NumPy, SciPy, and pandas, ensuring consistency and readability.
+- Coding style adheres to `PEP 8`_ and aligns with the conventions of major data science packages
+  like `numpy`_, `scipy`_, and `pandas`_, ensuring consistency and readability.
 - Documentation style emphasizes the significance of well-documented APIs,
   offering increased adoption, an improved on-boarding experiences, and streamlined code maintenance.
   All PyAnsys libraries follow the `Google developer documentation style guide

doc/source/coding-style/formatting-tools.rst

@@ -1,3 +1,5 @@
+.. _code_style_tools:
+
 Code style tools
 ================
 
@@ -256,22 +258,10 @@ Using ``tox``
 to make it highly customizable. Descriptions follow of some of the most
 widely used environments:
 
-- ``tox -e style`` checks the code style of your project.
-- ``tox -e py`` runs your test suite.
-- ``tox -e doc`` builds the documentation of your project.
+- ``tox -e style``: Checks the code style of your project.
+- ``tox -e py``: Runs your test suite.
+- ``tox -e doc``: Builds the documentation of your project.
 
 It is possible to run multiple environments by separating them with commas ``tox
 -e <env-name0>,<env-name1>,...```.  To run all available environments, simply
 run ``tox``.
-
-.. LINKS AND REFERENCES
-
-.. _Black: https://black.readthedocs.io/en/latest/
-.. _isort: https://pycqa.github.io/isort/
-.. _flake8: https://flake8.pycqa.org/en/latest/
-.. _pre-commit: https://pre-commit.com/
-.. _pytest: https://docs.pytest.org/en/latest/
-.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
-.. _tox: https://tox.wiki/en/latest/
-.. _PEP 8: https://www.python.org/dev/peps/pep-0008/
-.. _make: https://www.gnu.org/software/make/

doc/source/coding-style/index.rst

@@ -20,8 +20,7 @@ formatting with the libraries for the 'big three' data science packages: `numpy`
 `scipy`_, and `pandas`_. 
 
 The purpose of this section is not to repeat coding style documentation,
-but rather to describe coding best practices applicable to the `PyAnsys
-<https://pypi.org/project/pyansys/>`_ project when there are any
+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
 best practices because there is no official guidance on deprecating features
@@ -35,11 +34,3 @@ within Python.
    formatting-tools
    required-standard
    deprecation
-
-
-.. LINKS AND REFERENCES
-
-.. _NumPy: https://numpy.org/
-.. _SciPy: https://www.scipy.org/
-.. _pandas: https://pandas.pydata.org/
-.. _PEP 8: https://www.python.org/dev/peps/pep-0008/

doc/source/coding-style/pep8.rst

@@ -7,11 +7,6 @@ to increase the readability of Python code. Some of the most popular
 packages within the Python ecosystem have adopted `PEP 8`_,
 including `numpy`_, `scipy`_, and `pandas`_.
 
-.. _PEP 8: https://www.python.org/dev/peps/pep-0008/
-.. _numpy: https://numpy.org/
-.. _scipy: https://www.scipy.org/
-.. _pandas: https://pandas.pydata.org/
-
 Imports
 -------
 
@@ -25,8 +20,6 @@ module comments and docstrings and before module global variables 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
-
 .. tab-set::
 
    .. tab-item:: Use
@@ -147,9 +140,9 @@ Import namespaces
 ~~~~~~~~~~~~~~~~~
 
 You should avoid using wildcards in imports because doing so can make it
-difficult to detect undefined names. For more information, see `Python
-Anti-Patterns: using wildcard imports
+difficult to detect undefined names. For more information, see `using wildcard imports (from … import *)
 <https://docs.quantifiedcode.com/python-anti-patterns/maintainability/from_module_import_all_used.html>`_.
+in the *Python Anti-Patterns* documentation.
 
 .. tab-set::
 
@@ -226,8 +219,6 @@ When naming methods, follow these conventions:
 - Start a method that is to be considered private with double underscores.
 - Start a method that is to be considered protected with a single underscore.
 
-.. _dunder methods: https://docs.python.org/3/reference/datamodel.html#special-method-names
-
 .. code:: python
 
    class MyClass:
@@ -254,7 +245,7 @@ When naming methods, follow these conventions:
            these methods from being called from inherited classes.
 
            """
-           # note how we can call private methods here
+           # note how private methods can be called here
            self.__private_method()
 
        def public_method(self):

doc/source/conf.py

@@ -166,8 +166,16 @@
     "how-to/api/ansys_sphinx_theme.examples.samples.Complex.abs.rst",
     "how-to/api/ansys_sphinx_theme.examples.samples.Complex.imag.rst",
     "how-to/api/ansys_sphinx_theme.examples.samples.Complex.real.rst",
+    "links.rst",
 ]
 
+# make rst_epilog a variable, so you can add other epilog parts to it
+rst_epilog = ""
+
+# Read link all targets from file
+with open("links.rst") as f:
+    rst_epilog += f.read()
+
 # Fix excessive margins in mermaid output.
 # See issue: https://github.com/mermaid-js/mermaid/issues/1800#issuecomment-741617143
 mermaid_output_format = "png"
@@ -191,5 +199,14 @@
 linkcheck_ignore = [
     "https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi",  # Private URL hosting PyAnsys packages
     "https://github.com/ansys-internal/.*",  # Private URL
+    "https://myapps.microsoft.com/signin/8f67c59b-83ac-4318-ae96-f0588382ddc0?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706",  # Join Ansys GitHub account
+    "https://myapps.microsoft.com/signin/42c0fa04-03f2-4407-865e-103af6973dae?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706",  # Join Ansys internal GitHub account
 ]
+
+# Linkcheck ignore broken anchors
+linkcheck_anchors_ignore = [
+    # these anchors are picked by linkcheck as broken but they are not.
+    "38-comments-and-docstrings",
+]
+
 linkcheck_anchors_ignore_for_url = ["https://github.com/ansys/ansys-api-template"]

doc/source/content-writing/_static/README.md

@@ -0,0 +1 @@
+Static files can be found here (like images and other assets).

doc/source/content-writing/content-contrib-setup/client-libraries.rst

@@ -0,0 +1,37 @@
+.. _client_libs:
+
+Client libraries
+=================
+
+A client library is a collection of code specific to one programming language
+that makes it easier to write scripts to access APIs programmatically. A
+client library provides support for underlying services, including connection
+management, asynchronous request processing, and exception handling. Its
+high-level API abstractions are easier to understand and can be more
+easily integrated with your codebase.
+
+PyAnsys client libraries are collections of Python code that break apart
+large monolithic Ansys desktop products into subsets by features, with the
+expectation of compatibility and reusability across the entire Ansys
+portfolio. For more information, see :ref:`componentizing`. In addition
+to Ansys product wrappers, the PyAnsys ecosystem provides Python tools and
+software utilities.
+
+While installing a Python library depends on both the library and the
+underlying services that it supports, most are installed in only a few steps
+from the `Python Package Index <Python_Package_Index_>`_ (PyPI) using `pip <pip_>`_,
+a package manager for installing Python packages:
+
+#. Open a terminal or command prompt.
+#. Install ``pip`` if it is not already installed on your system.
+#. If you are using a `virtual environment <venv_>`_, activate it.
+#. Run the command to install the library, ``pip install <library-name>``, where
+   ``<library-name>`` is the name of the library.
+
+To easily set up your PyAnsys development environment and install PyAnsys libraries
+from one central source, you should use the **Ansys Python Manager**. From this app,
+you can install a selected Python version (which includes ``pip``), create and
+automatically activate a virtual environment, and install all or selected PyAnsys libraries.
+You can also launch a console in your virtual environment to run commands from. For more
+information, see :ref:`Ansys_Python_Manager`, which explains how to set up your content
+development environment.