diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml
index 6d32113a0..f864db5a9 100644
--- a/.github/workflows/ci_cd.yml
+++ b/.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:
diff --git a/doc/.vale.ini b/doc/.vale.ini
index f0905a58a..930dd2dde 100644
--- a/doc/.vale.ini
+++ b/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
\ No newline at end of file
+Google.Colons = NO
diff --git a/doc/source/abstractions/app-interface.rst b/doc/source/abstractions/app-interface.rst
index 4caf21aa6..14b1ab63f 100644
--- a/doc/source/abstractions/app-interface.rst
+++ b/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
diff --git a/doc/source/abstractions/data-transfer.rst b/doc/source/abstractions/data-transfer.rst
index dca4780d9..9853d13a4 100644
--- a/doc/source/abstractions/data-transfer.rst
+++ b/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 `_
-arrays or `pandas `_ 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/
diff --git a/doc/source/abstractions/service.rst b/doc/source/abstractions/service.rst
index 44d76dbef..3a85a3329 100644
--- a/doc/source/abstractions/service.rst
+++ b/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
`_. 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
diff --git a/doc/source/all-styles.rst b/doc/source/all-styles.rst
index 62b3571e0..cc803c455 100644
--- a/doc/source/all-styles.rst
+++ b/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
diff --git a/doc/source/coding-style/formatting-tools.rst b/doc/source/coding-style/formatting-tools.rst
index 711d63a80..7291282c1 100644
--- a/doc/source/coding-style/formatting-tools.rst
+++ b/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 ,,...```. 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/
diff --git a/doc/source/coding-style/index.rst b/doc/source/coding-style/index.rst
index b278c2a1b..fe52f8f17 100644
--- a/doc/source/coding-style/index.rst
+++ b/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
-`_ 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/
diff --git a/doc/source/coding-style/pep8.rst b/doc/source/coding-style/pep8.rst
index ba3755801..46304f04a 100644
--- a/doc/source/coding-style/pep8.rst
+++ b/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 *)
`_.
+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):
diff --git a/doc/source/conf.py b/doc/source/conf.py
index d23c3a09d..7ddc3c867 100755
--- a/doc/source/conf.py
+++ b/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"]
diff --git a/doc/source/content-writing/_static/AutoAPI-output-modified.png b/doc/source/content-writing/_static/AutoAPI-output-modified.png
new file mode 100644
index 000000000..4ed93b5e8
Binary files /dev/null and b/doc/source/content-writing/_static/AutoAPI-output-modified.png differ
diff --git a/doc/source/content-writing/_static/GitHub-about-area.png b/doc/source/content-writing/_static/GitHub-about-area.png
new file mode 100644
index 000000000..25a616547
Binary files /dev/null and b/doc/source/content-writing/_static/GitHub-about-area.png differ
diff --git a/doc/source/content-writing/_static/GitHub-line-selector-suggestions.png b/doc/source/content-writing/_static/GitHub-line-selector-suggestions.png
new file mode 100644
index 000000000..2bf308ba3
Binary files /dev/null and b/doc/source/content-writing/_static/GitHub-line-selector-suggestions.png differ
diff --git a/doc/source/content-writing/_static/README.md b/doc/source/content-writing/_static/README.md
new file mode 100644
index 000000000..0723e4fc8
--- /dev/null
+++ b/doc/source/content-writing/_static/README.md
@@ -0,0 +1 @@
+Static files can be found here (like images and other assets).
diff --git a/doc/source/content-writing/_static/card-dev-guide-home-page.png b/doc/source/content-writing/_static/card-dev-guide-home-page.png
new file mode 100644
index 000000000..9baf53308
Binary files /dev/null and b/doc/source/content-writing/_static/card-dev-guide-home-page.png differ
diff --git a/doc/source/content-writing/_static/card-docker-containers-pyansys-geometry.png b/doc/source/content-writing/_static/card-docker-containers-pyansys-geometry.png
new file mode 100644
index 000000000..11d410fbe
Binary files /dev/null and b/doc/source/content-writing/_static/card-docker-containers-pyansys-geometry.png differ
diff --git a/doc/source/content-writing/_static/icon-add-suggestion.png b/doc/source/content-writing/_static/icon-add-suggestion.png
new file mode 100644
index 000000000..ab6c49af8
Binary files /dev/null and b/doc/source/content-writing/_static/icon-add-suggestion.png differ
diff --git a/doc/source/content-writing/_static/multi-version-doc-selector.png b/doc/source/content-writing/_static/multi-version-doc-selector.png
new file mode 100644
index 000000000..11e6311ab
Binary files /dev/null and b/doc/source/content-writing/_static/multi-version-doc-selector.png differ
diff --git a/doc/source/content-writing/_static/notice-new-package-release.png b/doc/source/content-writing/_static/notice-new-package-release.png
new file mode 100644
index 000000000..606c1b670
Binary files /dev/null and b/doc/source/content-writing/_static/notice-new-package-release.png differ
diff --git a/doc/source/content-writing/_static/notice-recent-pushes.png b/doc/source/content-writing/_static/notice-recent-pushes.png
new file mode 100644
index 000000000..155bafd40
Binary files /dev/null and b/doc/source/content-writing/_static/notice-recent-pushes.png differ
diff --git a/doc/source/content-writing/_static/tab-set-double-dev-guide.png b/doc/source/content-writing/_static/tab-set-double-dev-guide.png
new file mode 100644
index 000000000..b47a22f5c
Binary files /dev/null and b/doc/source/content-writing/_static/tab-set-double-dev-guide.png differ
diff --git a/doc/source/content-writing/_static/tab-set-single-dev-guide.png b/doc/source/content-writing/_static/tab-set-single-dev-guide.png
new file mode 100644
index 000000000..22689494b
Binary files /dev/null and b/doc/source/content-writing/_static/tab-set-single-dev-guide.png differ
diff --git a/doc/source/content-writing/content-contrib-setup/client-libraries.rst b/doc/source/content-writing/content-contrib-setup/client-libraries.rst
new file mode 100644
index 000000000..6c5e670d8
--- /dev/null
+++ b/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 `_ (PyPI) using `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 `_, activate it.
+#. Run the command to install the library, ``pip install ``, where
+ ```` 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.
diff --git a/doc/source/content-writing/content-contrib-setup/content-dev-environment.rst b/doc/source/content-writing/content-contrib-setup/content-dev-environment.rst
new file mode 100644
index 000000000..609c23009
--- /dev/null
+++ b/doc/source/content-writing/content-contrib-setup/content-dev-environment.rst
@@ -0,0 +1,379 @@
+.. _dev_environment_writers:
+
+Content development environment
+===============================
+
+Before you can contribute to PyAnsys documentation, you must set up your
+content development environment. Setup consists of creating a few accounts and
+installing some apps and tools.
+
+If you intend only to :ref:`review PRs ` created by others, you do not
+have to set up a full content development environment. Instead, you need only perform the
+steps in these topics:
+
+- :ref:`doc_for_create_github_account`
+- :ref:`install_git`
+- :ref:`join_ansys_github_orgs`
+
+If you intend to :ref:`create your own PRs `, perform the steps in all
+topics to set up a full content development environment.
+
+.. _doc_for_create_github_account:
+
+Create a GitHub account
+-----------------------
+
+`GitHub `_ is a web-based platform with more than 100 million users
+and 330 million repositories. A repository contains everything about a project
+and is the root of the project.
+
+While GitHub uses the `Git version control system `_ for tracking changes
+in source code, it goes way beyond version control, offering a
+collaborative environment for hosting, managing, and sharing Git repositories.
+
+To view or contribute to a GitHub project, you must have a GitHub user account.
+
+#. Go to the `Join GitHub `_ page and complete the user account form.
+#. Once your account is created, set it up to require two-factor authentication.
+ For more information, see `Configuring two-factor authentication
+ `_ in the GitHub documentation.
+
+In a GitHub project, you can perform many tasks, including these:
+
+- Browse the codebase to explore the project's structure and architecture.
+
+- Read the project-hosted documentation to understand how the project works,
+ how to use it effectively, and how to contribute.
+
+- Review a PR created by a fellow contributor to ensure that the code being
+ added or changed meets established coding standards, follows best practices,
+ and is of high quality before the PR can be approved for merging into the
+ codebase.
+
+- Create a local branch, make commits with suggested additions or changes, and
+ then create your own PR for project maintainers to review, approve, and merge.
+
+- Integrate CI/CD (continuous integration/continuous deployment).
+
+- Automate testing and deployment processes.
+
+- Manage discussions and build a community around your project.
+
+While some of the preceding GitHub tasks are usually performed only by project
+maintainers, many of them are regularly performed by all team members, including
+content contributors.
+
+For more information on GitHub, see :ref:`Contributing` and the `GitHub documentation `_.
+
+.. _install_git:
+
+Install Git
+-----------
+
+You must have `Git `_ or a graphical user interface (GUI) client for Git installed.
+
+Because developers are accustomed to working in terminal environments, they
+tend to prefer using the Git command line, especially because it provides for
+greater control, customization, and automation. However, non-developer team members, such
+as project managers, designers, and writers, tend to prefer using a GUI client for Git.
+
+With a GUI client like `GitHub Desktop `_ or `Git Extensions `_,
+rather than having to remember complex command sequences, non-developer team members can use the
+visual clues that the GUI provides to better understand branching, PRs,
+merging, and history visualization.
+
+If you do not yet have Git or a GUI client for Git installed, install your
+preferred tool from an official channel.
+
+.. _join_ansys_github_orgs:
+
+Join Ansys GitHub organizations
+-------------------------------
+
+Ansys has two GitHub organizations:
+
+- ``ansys``: Contains Ansys public repositories
+- ``ansys-internal``: Contains Ansys internal repositories
+
+Ansys employees can join these Ansys organizations by clicking the following
+links to sign in first with their Ansys credentials and then with their
+GitHub credentials.
+
+- Join the `Ansys GitHub organization `_.
+- Join the `Ansys Internal GitHub organization `_.
+
+Writers outside of Ansys who want to contribute to the documentation for a PyAnsys
+library can email `pyansys.core@ansys.com `_
+for permission to access this project's repository.
+
+.. _Ansys_Python_Manager:
+
+Install and use the Ansys Python Manager
+----------------------------------------
+
+Because installing Python on Windows is a complex process for people new to
+the Python ecosystem, various groups within Ansys have worked together to
+create the **Ansys Python Manager**, an open source Python QT app. This app streamlines
+installing Python on Windows, simplifies creating and managing virtual environments,
+centralizes installing and using other development tools, and facilitates both
+installing PyAnsys packages and viewing PyAnsys documentation.
+
+While `Ansys Python Manager documentation `_ is available,
+you can perform these steps to install and immediately begin using this app:
+
+#. Go to the `Releases `_ page in the ``python-installer-qt-gui``
+ repository.
+
+#. To download the executable (EXE) file for the latest release, under **Assets**,
+ click **Ansys-Python-Manager-Setup-v[latest version].exe**.
+
+#. In your **Downloads** directory, double-click this EXE file to open the **Ansys
+ Python Manager Setup** window, where you can accept the defaults on each page.
+
+ When the installation completes, the Ansys Python Manager opens. If you close
+ this app, you can open it again at any time from the Windows **Start** menu by
+ selecting **Ansys Python Manager**.
+
+#. On the **Install Python** tab, install a selected Python version:
+
+ #. For **Installation type**, choose **Standard** to install the standard
+ installation from the `Python `_ organization.
+
+ #. For **Python version**, choose **Python 3.11** to install the latest available
+ version.
+
+ #. At the bottom of the page, click **Install**.
+
+ A **Setup Progress** window opens while Python is being installed and
+ then closes when the installation finishes.
+
+#. On the **Create virtual environments** tab, create and activate a virtual environment:
+
+ #. For **Select Python version**, choose the Python version that you want to
+ create a virtual environment for.
+
+ You likely have only the one Python version that you just installed.
+ However, developers might have several Python versions installed.
+
+ A virtual environment makes your life easier because you do not have
+ to worry about dependency conflicts in the same environment. For more information,
+ see `Creation of virtual environments `_ in the
+ Python documentation.
+
+ #. For **Virtual environment name**, type the name to give your virtual environment.
+
+ For example, type ``my_venv``.
+
+ #. At the bottom of the page, click **Create**.
+
+ After a few seconds, an **Information** window opens, indicating that your
+ virtual environment has been successfully created. As indicated on the tab, virtual
+ environments are created in an ``.ansys_python_venvs`` folder in your user directory.
+
+ #. Click **OK** to close the **Information** window.
+
+#. On the **Manage Python Environments** tab, use some of its many features to set up and
+ explore your development environment:
+
+ #. For **Available virtual environments**, choose the virtual environment
+ that you have just created.
+
+ Writers generally find having one virtual environment sufficient. However, developers
+ might have several virtual environments for managing different packages and
+ launching options.
+
+ #. Under **General package management**, click **Install Python default packages** to install
+ all the open source packages that are commonly used by PyAnsys libraries in your virtual
+ environment.
+
+ The **Administrator** window opens, showing the installation of the default packages.
+ Once these packages are installed, this window closes.
+
+ #. To see a list of all packages installed in your virtual environment, under
+ **General package management** in the app, click **List installed packages**.
+
+ The **Administrator** window opens, showing the names and versions of all installed packages.
+
+ If you create an issue on the **Issues** page for a project's GitHub repository, you are
+ asked for your Python version, which you selected on the **Install Python** tab, and
+ your installed packages. You can copy the package information from here in the **Administrator**
+ window and paste it into the issue template.
+
+ If a new release of an installed package is available, in addition to listing the installed
+ packages, the **Administrator** window displays notices, which include the command for updating
+ to the new release. Thus, you should periodically click **List installed packages** to see if
+ you need to update an installed package.
+
+ .. image:: ..//_static/notice-new-package-release.png
+ :alt: New package release notices
+
+ After copying the update command for a package, you can paste it in the command prompt,
+ which is the final line in the window that shows the name of your virtual environment in
+ parentheses. You then press the **enter** key to run the command. The window displays
+ information about uninstalling the current package and installing the updated package.
+
+ When finished, close the **Administrator** window.
+
+ #. Under **PyAnsys package management**, choose the PyAnsys package to install,
+ the desired version, and click **Install**.
+
+ Choosing **PyAnsys-Metapackge** and an Ansys version installs all PyAnsys
+ packages that are compatible for use with this Ansys version. While you can choose
+ to install a metapackage for a particular Ansys version, if you are contributing
+ to PyAnsys documentation for only one package, or only for a few packages, choosing
+ to install only these individual packages saves disk space.
+
+ Once the package is installed, this window closes.
+
+#. From the app's **File** menu, periodically select **Check for Updates** to check for and install
+ any updates available for the Ansys Python Manager.
+
+#. From the app's **Help** menu, select **Online Documentation** to see this app's documentation.
+ If this app is not open, you can go directly to the latest stable version of the
+ `Ansys Python Manager documentation `_ on GitHub.
+
+#. From the app's **Help** menu, select **PyAnsys Documentation** to open the **PyAnsys Documentation**
+ window, where you can choose the documentation that you want to view. Then, click **Open Website**
+ to go directly to this documentation. When finished, you can close this window.
+
+While you can close and reopen the Ansys Python Manager as needed, leaving this app open while you work
+is helpful because you can click **Launch console** under **Launch options** to open a console to run commands
+in your virtual environment.
+
+If you click any other button under **Launch options**, the Ansys Python Manager installs this tool
+if it is not yet installed and then opens it. However, most of these tools are for developers and project
+maintainers who use them to write and test Python scripts. Because editing the reStructuredText
+(RST) and Python (PY) files for PyAnsys documentation is more easily accomplished using Visual Studio
+Code and the Python in Visual Studio Code extension, you likely do not need to use these other tools.
+
+Install Visual Studio Code
+--------------------------
+
+`Visual Studio Code `_ is a lightweight but powerful source code editor that
+runs on your desktop. As indicated in the `Visual Studio Code documentation `_,
+it is available for Windows, macOS, and Linux. For information on installing and
+running Visual Studio Code on your operating system, see `SETUP `_ in the
+Visual Studio Code documentation.
+
+While you can use another source code editor to modify RST and PY files, Visual Studio Code is
+one of the most commonly used source code editors worldwide. This guide assumes that you are
+using Visual Studio Code with the Python in Visual Studio Code extension.
+
+Install the Python in Visual Studio Code extension
+--------------------------------------------------
+The Python in Visual Studio Code extension makes Visual Studio Code an excellent Python editor.
+This extension, which works on any operating system with a variety of Python interpreters,
+leverages Visual Studio Code's power to provide autocompletion and IntelliSense, linting,
+debugging, and unit testing.
+
+Install the Python in Visual Studio Code extension:
+
+#. From the **View** menu in Visual Studio Code, select **Extensions**.
+#. At the top of the **EXTENSIONS** pane, type ``python`` in the search box to filter the
+ list of available extensions.
+#. Select the Python extension published by Microsoft, which is described as IntelliSense
+ (Pylance) and is usually the first one in the list.
+
+ You can view information about this extension in the main pane on the right.
+
+#. In either the **EXTENSIONS** pane or the main pane, click **Install**.
+
+The **Install** button changes to a settings (gear) icon in the **EXTENSIONS** pane or to
+two buttons, **Disable** and **Uninstall**, in the main pane. This lets you know that the
+Python extension for Windows has been installed successfully.
+
+Install pre-commit
+------------------
+
+`pre-commit `_ is a tool for ensuring that all the changes that you make to
+files in a project successfully pass all checks run by the code style tools that are
+configured as part of the CI/CD process. For more information on the code style tools most
+commonly used in PyAnsys projects, see :ref:`code_style_tools`.
+
+To run ``pre-commit`` locally, you must install it in your development environment:
+
+#. If the Ansys Python Manager and **Administrator** window are not still
+ open, open them.
+#. From the **Administrator** window's command prompt, run this command::
+
+ python -m pip install pre-commit
+
+ The window displays installation information.
+
+.. _install_Vale_locally:
+
+Install Vale
+------------
+
+`Vale `_ is a tool for maintaining a consistent style and voice in your
+documentation based on a given style guide. When the `Ansys templates `_
+tool is used to create a PyAnsys project from the ``pyansys`` or ``pyansys-advanced`` template,
+Vale is one of the many documentation style tools that is configured to run as part of the
+CI/CD process. For more information, see :ref:`doc_style_tools`.
+
+To run Vale locally, you must install it in your development environment:
+
+#. If the Ansys Python Manager and **Administrator** window are not still
+ open, open them.
+#. From the **Administrator** window's command prompt, run this command to
+ install Vale::
+
+ python -m pip install vale
+
+ The window displays installation information.
+
+.. todo::
+ Talk to the PyAnsys team about this approach. They said that this ``pip`` package is not
+ official. I have, however, been using it locally for a month or so.
+
+Install Notepad\+\+
+-------------------
+Links for using various GitHub search functions are available in `Search on GitHub documentation
+`_ in the GitHub documentation. However, to find occurrences of a
+particular word or phrase in a project, using `Notepad\+\+ `_ is often easier. This app's
+**Find in Files** option provides for quickly searching any given directory for a search string.
+For installation and search information, see `Downloads `_ on the Notepad\+\+ website and
+`Searching `_ in the *Notepad\+\+ User Manual*.
+
+.. tip::
+ Notepad\+\+ is also handy if you want to open one file in it to visually compare it to
+ another file that you have open in Visual Studio Code.
+
+Install Sphinx and the Ansys Sphinx theme
+-----------------------------------------
+`Sphinx `_, which uses reStructuredText as its default plaintext markup language, is
+a tool for generating documentation. While designed primarily for generating documentation
+for Python projects, it can be used for generating documentation for other programming languages
+and projects.
+
+The `Ansys Sphinx theme `_ is an Ansys-branded extension of the popular
+`PyData Sphinx theme `_. It is used along with Sphinx to assemble PyAnsys
+documentation from a project's RST files and the docstrings in its PY files.
+
+Install both Sphinx and the Ansys Sphinx theme so that you can build PyAnsys documentation
+locally:
+
+#. If the Ansys Python Manager and **Administrator** window are not still
+ open, open them.
+#. To install Sphinx in your virtual environment from PyPI (Python Package Index),
+ from the **Administrator** window's command prompt, run this command::
+
+ pip install -U sphinx
+
+ The window displays installation information.
+
+#. To see the version of the installed Sphinx package, run this command::
+
+ sphinx-build --version
+
+#. To install the Ansys-branded theme, run this command::
+
+ python -m pip install ansys-sphinx-theme
+
+ The window displays installation information. The Sphinx ``conf.py`` file
+ in the ``doc`` directory of a PyAnsys repository is already configured to use
+ this theme.
+
+Your development environment is now set up. If you are new to contributing to
+PyAnsys documentation, see :ref:`essentials_writers`. For lists of resources related
+to contributing to PyAnsys documentation, see :ref:`resources_writers`.
diff --git a/doc/source/content-writing/content-contrib-setup/doc-resources.rst b/doc/source/content-writing/content-contrib-setup/doc-resources.rst
new file mode 100644
index 000000000..7874f9115
--- /dev/null
+++ b/doc/source/content-writing/content-contrib-setup/doc-resources.rst
@@ -0,0 +1,102 @@
+.. _resources_writers:
+
+PyAnsys documentation resources
+===============================
+
+This page lists resources relevant to contributing to PyAnsys documentation.
+While other pages reference resources as needed, this page provides a central
+location from which you can easily view all referenced resources.
+
+.. _style_format_resources:
+
+Style and formatting resources
+------------------------------
+The following alphabetized list of resources provide guidelines for writing PyAnsys
+documentation. These resources provide you with an understanding of how to write
+and format PyAnsys documentation content correctly in various types of source files.
+
+- `GitHub Flavored Markdown Spec `_: Describes how GitHub
+ Flavored Markdown is a dialect of Markdown supported for user content on GitHub.com and
+ GitHub Enterprise. Generally, all manually written source files for PyAnsys documentation
+ are RST files. However, some projects use a GitHub Flavored Markdown (MD) file for the
+ project's README file. For more information, see :ref:`readme_files`.
+- `Google developer documentation style guide `_: Provides
+ guidance on the writing style used for PyAnsys documentation.
+- `Material for Sphinx `_: Provides guidance on authoring in
+ reStructuredText when using Sphinx to generate documentation and includes a
+ reStructuredText cheat sheet.
+- `numpydoc Style guide `_: Provides the syntax and best practices for
+ writing docstrings in PY files when the ``numpydoc`` extension for Sphinx is used. Docstrings
+ describe Python modules, functions, classes, and methods. This guide's overview also provides
+ links to standard Python code conventions, additional PEPs (Python Enhancement Proposals) related
+ to the documentation of code, and common code style checkers.
+- `PEP 8 - Style Guide for Python Code `_: Provides guidance on the Python coding
+ style that PyAnsys libraries use.
+- `Python documentation `_: Provides the official documentation published by the
+ Python organization for Python for developers at all levels.
+- `Quick reStructuredText `_: Provides a summary of reStructuredText
+ syntax with links to the `reStructuredText Markup Specification `_
+ for more comprehensive information.
+- `reStructuredText Markup Specification `_: Provides a quick reStructuredText
+ syntax overview, which explains that the parser is a component of `Docutils `_,
+ an open source text-processing system for plaintext documentation. It then provides the complete
+ technical specification.
+- `reStructuredText Markup Syntax and Parser Component of Docutils `_:
+ Provides a description of reStructuredText and links to user, reference, and developer
+ documentation, including a reStructuredText cheat sheet.
+- `reStructuredText Primer `_: Provides introductory documentation on reStructuredText
+ concepts and syntax as part of the `documentation `_.
+- `Style guide for Sphinx-based documentation `_: Provides coding
+ standards for Sphinx-based documentation.
+- `Using Markdown and Liquid in GitHub Docs `_: Provides an
+ explanation of GitHub Flavored Markdown and explains how GitHub docs use `Liquid `_
+ syntax to expand the functionality to provide accessible tables, maintainable links, versioning,
+ variables, and chunks of reusable content.
+
+.. _tool_resources:
+
+Tool resources
+--------------
+The following alphabetized list of resources are for tools used in the writing and
+building of PyAnsys documentation.
+
+- `Ansys Python Manager `_: Provides a cross-platform
+ QT app for installing Python and managing your Python environment, including creating
+ virtual environments, launching a command console, installing PyAnsys packages, and
+ viewing PyAnsys documentation.
+- `Ansys Sphinx theme `_: Provides an Ansys-branded extension
+ of the popular `PyData Sphinx theme `_ that is used to generate
+ PyAnsys documentation.
+- `Ansys templates `_: Provides templates for creating PyAnsys projects
+ that are compliant with PyAnsys guidelines.
+- `Git `_: Provides a distributed version control system for tracking changes
+ in source code during software development.
+- `Git Extensions `_: Provides a GUI client for Git.
+- `GitHub `_: Provides a web-based platform that uses Git as its underlying
+ version control system but goes way beyond version control, offering a
+ collaborative environment for hosting, managing, and sharing Git repositories.
+- `GitHub Desktop `_: Provides a GUI client for Git.
+- `Notepad\+\+ `_: Provides an open source code text and code editor for use
+ on Microsoft Windows, supporting around 80 programming languages with syntax
+ highlighting and code folding.
+- `pip `_: Provides a package manager for installing Python packages from the
+ `Python Package Index `_ (PyPI).
+- `pre-commit `_: Provides for checking the conformance of your code
+ against predefined code style conventions.
+- `Python `_: Provides a general-purpose programming language that runs on
+ almost all system architectures and is used for a wide range of applications
+ in different fields.
+- `Python in Visual Studio Code `_: Provides an extension
+ that makes `Visual Studio Code `_ an excellent Python editor.
+- `Sphinx `_: Provides a Python documentation generator for generating documentation
+ from RST, MD, and PY files.
+- `Vale `_: Provides for checking RST and MD files for consistent
+ style and voice.
+- `Visual Studio Code `_: Provides a lightweight but powerful source
+ code editor that runs on your desktop and is available for WIndows , macOS, and Linux.
+
+.. note::
+
+ For information on documentation style tools that might be implemented in
+ a PyAnsys project but are not necessarily described on this page, see
+ :ref:`doc_style_tools`.
diff --git a/doc/source/content-writing/content-contrib-setup/essentials.rst b/doc/source/content-writing/content-contrib-setup/essentials.rst
new file mode 100644
index 000000000..c898e1572
--- /dev/null
+++ b/doc/source/content-writing/content-contrib-setup/essentials.rst
@@ -0,0 +1,81 @@
+.. _essentials_writers:
+
+Essentials for content writing
+==============================
+
+This page provides essential information for writing content for PyAnsys documentation.
+
+These earlier topics are also related to documentation or contributing to a PyAnsys
+library:
+
+- :ref:`documenting_developers` provides an overview of key documentation concepts
+ along with some how-to information.
+
+- :ref:`doc_style_developers` provides valuable information about API documentation,
+ Sphinx configuration, NumPy-style docstrings, documentation generation, and tools
+ for documentation style and coverage.
+
+- :ref:`contributing` provides the general coding paradigms for PyAnsys development
+ that you must understand before contributing to a PyAnsys library.
+
+Google developer documentation style guide
+------------------------------------------
+
+All contributors to PyAnsys documentation must follow the guidelines in the
+`Google developer documentation style guide `_.
+While you should become familiar with this entire style guide, periodically revisit the
+`Highlights `_ page to ensure that you are adhering to its most important points.
+
+When the `Ansys templates `_ tool is used to create a PyAnsys project from the
+``pyansys`` or ``pyansys-advanced`` template, `Vale `_, a rule-based tool for maintaining
+a consistent style and voice in your documentation, is implemented. This tool, which is one of
+many run by the CI/CD process, is configured to check content in RST and Markdown (MD) files
+based on the *Google developer documentation style guide*.
+
+To eliminate or mitigate the number of warnings and errors that Vale raises in a PR, you can install
+Vale locally and then run it before you create or submit changes to a PR. For more information,
+see :ref:`install_Vale_locally` and :ref:`run_Vale_locally`.
+
+PyAnsys documentation
+---------------------
+
+On the right of the home page for a PyAnsys library's GitHub repository, the **About** area
+has a link to the library's documentation. For example, here is the **About** area
+for this guide:
+
+.. image:: ..//_static/GitHub-about-area.png
+ :alt: **About** area with link to the *PyAnsys developer's guide*
+
+You can also view the documentation for public PyAnsys libraries from the
+`PyAnsys `_ landing page or from the Ansys Python Manager by
+selecting **Help > PyAnsys Documentation**. For more information about this Python QA
+app, see :ref:`Ansys_Python_Manager`.
+
+All links to PyAnsys documentation take you to documentation for the stable (latest)
+release because this is what users of the library generally want to see. In some cases,
+users might want to see documentation for a legacy version of the library. Project contributors,
+on the other hand, likely want to see the documentation for the development (main) branch of the
+library.
+
+Rather than hosting many separate documentation sites, the PyAnsys team supports enabling *multi-versions*,
+which makes it possible for you to select the documentation for different versions from a dropdown button
+on the right side of the documentation title bar.
+
+.. image:: ..//_static/multi-version-doc-selector.png
+ :alt: Version selector
+
+This dropdown button provides for selecting the documentation for the stable version, development (dev)
+version, and three previous legacy versions by default. However, the selections it displays
+can be customized. For more information on enabling and customizing this
+dropdown button, see :ref:`multi_version_enabling`.
+
+To edit and contribute to the documentation for the development branch, you should select
+ **dev** from this dropdown to view the documentation for the main branch.
+
+.. tip::
+ When you are viewing PyAnsys documentation, the right navigation pane typically
+ displays **Show Source** and **Edit on GitHub** links. For information on using
+ the **Show Source** link to see how a page's source file is formatted and how
+ you can reuse this content, see :ref:`rst_file_formatting`. For information on
+ using the **Edit on GitHub** link to use the GitHub web editor to submit
+ suggested changes to a page in a PR, see :ref:`edit_on_GitHub`.
diff --git a/doc/source/content-writing/content-contrib-setup/index.rst b/doc/source/content-writing/content-contrib-setup/index.rst
new file mode 100644
index 000000000..c4ba79e7c
--- /dev/null
+++ b/doc/source/content-writing/content-contrib-setup/index.rst
@@ -0,0 +1,33 @@
+.. _content_contrib_setup:
+
+Content contribution setup
+##########################
+
+Python's vast ecosystem of mathematical and scientific computing tools
+is widely used for data analysis. PyAnsys is a collection of Python-based,
+open source projects tailored specifically for engineers who want to automate
+their simulation workflows and extend the capabilities of Ansys products.
+
+This section describes Python client libraries and explains how to
+set up your development environment for contributing to the documentation
+for PyAnsys libraries.
+
+- A Python client library is a collection of source files.
+- A package is a superset of the Python client library. It includes all source
+ files and the supporting files needed to install and use the library.
+
+Additionally, this section provides essential information for
+documenting PyAnsys libraries and includes links to all the many
+resources relevant to creating and maintaining this documentation. The
+:ref:`resources_writers` page and the :ref:`content_how_tos` section are
+likely to be the content that you refer to most as you become proficient
+in contributing to PyAnsys documentation.
+
+.. toctree::
+ :maxdepth: 3
+ :hidden:
+
+ client-libraries
+ content-dev-environment
+ essentials
+ doc-resources
diff --git a/doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst b/doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst
new file mode 100644
index 000000000..62dd720b1
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/add-sphinx-extensions.rst
@@ -0,0 +1,226 @@
+.. _add_sphinx_extensions:
+
+Add Sphinx extensions
+=====================
+
+The Sphinx configuration (``doc/source/conf.py``) file contains an ``extensions``
+variable that specifies the list of extensions that are configured for use by
+Sphinx when generating documentation. When the `Ansys templates `_
+tool is used to create a PyAnsys project from the ``pyansys`` or ``pyansys-advanced``
+template, the ``extensions`` variable lists these extensions by default:
+
+.. code::
+
+ # Sphinx extensions
+ extensions = [
+ "sphinx.ext.autodoc",
+ "sphinx.ext.autosummary",
+ "numpydoc",
+ "sphinx.ext.intersphinx",
+ "sphinx_copybutton",
+ ]
+
+Extensions with names beginning with ``sphinx_ext`` are native (built-in) and are
+available for Sphinx's use without any additional installation. Extensions with names
+that do not begin with ``sphinx_ext`` are external extensions and require installation.
+If an extension is not configured properly, attempts to build the documentation fail
+because Sphinx cannot find the needed extension.
+
+.. _links_to_objects_in_other_doc:
+
+Link to Python objects in other Sphinx documentation
+----------------------------------------------------
+
+The ``sphinx.ext.intersphinx`` extension is configured by default in your project's
+:file:`conf.py` file so that you can link to Python objects in other Sphinx documentation.
+The ``intersphinx_mapping`` variable specifies the URIs for the Sphinx documentation with
+the objects that you want to link to.
+
+For example, this ``intersphinx_mapping`` variable provides mappings to the Sphinx documentation
+for several other projects:
+
+.. code::
+
+ # Intersphinx mapping
+ intersphinx_mapping = {
+ "python": ("https://docs.python.org/3/", None),
+ "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+ "numpy": ("https://numpy.org/doc/stable/", None),
+ "matplotlib": ("https://matplotlib.org/stable/", None),
+ "pandas": ("https://pandas.pydata.org/docs/", None),
+ "pyvista": ("https://docs.pyvista.org/version/stable/", None),
+ "grpc": ("https://grpc.github.io/grpc/python/", None),
+ "pypim": ("https://pypim.docs.pyansys.com/version/dev/", None),
+ "ansys-dpf-core": ("https://dpf.docs.pyansys.com/version/stable/", None),
+ "ansys-math-core": ("https://math.docs.pyansys.com/version/stable/", None),
+ }
+
+To be able to link to a Python object in other Sphinx documentation, the object must be part
+of that documentation's inventory (:file:`object.inv`) file. You map the target (base URI of
+the external documentation or the local path) to the documentation's :file:`object.inv`
+file. The keyword ``None`` indicates that this file is found at the same location. If it is not,
+you must supply the appropriate URI.
+
+Given that a target for a Python object exists in the Sphinx documentation that you want to
+link to, you can link to it using the same roles that you use to link to a Python object in
+your documentation. Here are some examples:
+
+- SciPy ``odeint()`` function:
+
+ - ``:func:`odeint() ` odeint()``
+ - ``:func:`scipy.integrate.odeint` scipy.integrate.odeint()``
+
+- SciPy ``quad()`` function:
+
+ - ``:func:`quad() ` quad()``
+ - ``:func:`scipy.integrate.quad` scipy.integrate.quad()``
+
+- Matplotlib ``hist()`` method:
+
+ - ``:meth:`hist() ` hist()``
+ - ``:meth:`matplotlib.axes.Axes.hist` matplotlib.axes.Axes.hist()``
+
+- NumPy module:
+
+ - ``:mod:`numpy ` numpy``
+ - ``:mod:`numpy` numpy``
+
+- NumPy ``matrix`` class:
+
+ - ``:class:`matrix ` matrix``
+ - ``:class:`numpy.matrix.` numpy.matrix``
+
+- NumPy matrix attribute shape:
+
+ - ``:attr:`shape() ` shape()``
+ - ``:attr:`numpy.ndarray.shape` numpy.ndarray.shape``
+
+For more information, see :ref:`API_object_links`.
+
+Add a native extension
+----------------------
+
+To use the special features provided by a native Sphinx extension, you only need to add
+the extension to the ``extensions`` variable in the project's :file:`conf.py`
+file.
+
+For example, the native ``sphinx.ext.todo`` extension was added to the ``extensions``
+variable in the :file:`conf.py` file for this guide. This extension supports
+use of the ``todo`` directive to create a specially formatted block of text for
+a task that must still be done. The blocks for ``todo`` directives do not render
+in the documentation by default. However, to render them in the documentation, you
+can add a ``todo_include_todos`` variable to the :file:`conf.py` file and then set
+this variable to ``True``.
+
+Add an external extension
+-------------------------
+
+To use the special features provided by an external Sphinx extension is a bit
+more complicated. You must install the extension in your development environment and then
+add it to both the project's :file:`conf.py` and its list of documentation requirements.
+
+For example, to use cards and tab sets in your documentation, you must install and configure
+the external `sphinx-design `_ extension for use:
+
+#. If the Ansys Python Manager and **Administrator** window are not still
+ open, open them.
+#. From the **Administrator** window's command prompt, run the command
+ for installing the external extension in your development environment::
+
+ python -m pip install
+
+ For example, to install the external ``sphinx-design`` extension, run this command::
+
+ python -m pip install sphinx-design
+
+#. Add the external extension to the ``extensions`` variable in your project's
+ :file:`conf.py` file.
+
+#. Add the external extension to your project's documentation requirements as indicated
+ in the next topic.
+
+.. _doc_ext_requirements:
+
+Add the extension to the documentation requirements
+---------------------------------------------------
+
+Documentation requirements list the ``pip`` packages that Sphinx requires for
+building the documentation. Depending on the project's configuration, you list these
+packages in either the :file:`pyproject.toml` file or the :file:`requirements_doc_txt`
+file.
+
+``pyproject.toml`` file
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Most projects specify documentation requirements in a :file:`pyproject.toml` file, which
+resides in the root folder. In this file, the ``doc`` variable defines the required ``pip``
+packages and their versions like this.
+
+.. code::
+
+ doc = [
+ "ansys-sphinx-theme==0.12.3",
+ "docker==6.1.3",
+ "ipyvtklink==0.2.3",
+ "jupyter_sphinx==0.4.0",
+ "jupytext==1.15.2",
+ "myst-parser==2.0.0",
+ "nbconvert==7.9.2",
+ "nbsphinx==0.9.3",
+ "notebook==7.0.5",
+ "numpydoc==1.6.0",
+ "panel==1.2.3",
+ "pyvista[trame]==0.41.1",
+ "requests==2.31.0",
+ "sphinx==7.2.5",
+ "sphinx-autoapi==3.0.0",
+ "sphinx-autodoc-typehints==1.24.0",
+ "sphinx-copybutton==0.5.2",
+ "sphinx_design==0.5.0",
+ "sphinx-jinja==2.0.2",
+ "vtk==9.2.6",
+ ]
+
+``requirements_doc_txt`` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some projects specify documentation requirements in a :file:`requirements_doc_txt`
+file. The root folder of such a project typically has a ``requirements`` directory
+that contains this TXT file, which defines the required ``pip`` packages and their
+versions like this:
+
+.. code::
+
+ Sphinx==7.1.2
+ jupyter_sphinx==0.4.0
+ numpydoc==1.5.0
+ matplotlib==3.7.2
+ ansys-sphinx-theme==0.10.2
+ pypandoc==1.11
+ pytest-sphinx==0.5.0
+ sphinx-autobuild==2021.3.14
+ sphinx-autodoc-typehints==1.24.0
+ sphinx-copybutton==0.5.2
+ sphinx-gallery==0.13.0
+ sphinx-notfound-page==0.8.3
+ sphinxcontrib-websupport==1.2.5
+ sphinxemoji==0.2.0
+ autodocsumm==0.2.11
+
+Learn more about extensions
+---------------------------
+
+As you can see, PyAnsys projects add many extensions to their :file:`conf.py` files
+and documentation requirements. Here are some additional extensions that you might see:
+
+- ``sphinx.ext.coverage``
+- ``sphinx.ext.doctest``
+- ``sphinx.ext.extlinks``
+- ``sphinx.ext.graphviz``
+- ``sphinx.ext.napoleon``
+- ``sphinx.ext.viewcode``
+
+For more information on extensions, see `Extensions `_ in the
+Sphinx documentation. In addition to the external (third-party) extensions collected
+in the `sphinx-contrib `_ organization, you can search the internet
+to find other Sphinx extensions or learn more about the ones in the preceding list.
diff --git a/doc/source/content-writing/content-how-tos/clone-branch.rst b/doc/source/content-writing/content-how-tos/clone-branch.rst
new file mode 100644
index 000000000..8d50463a6
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/clone-branch.rst
@@ -0,0 +1,80 @@
+.. _clone_branch:
+
+Clone and branch a repository
+=============================
+
+This page describes how to clone (download) a GitHub repository and then provides
+conceptual information on how you use your Git tool to create a local branch where
+you modify or add to the codebase, eventually submitting your suggested changes in
+a PR to the GitHub repository. For Git-related procedural information, see the
+documentation for your preferred Git tool.
+
+.. _clone_repo:
+
+Clone a repository
+------------------
+
+Before you can contribute to a PyAnsys project, you must clone the GitHub
+repository.
+
+#. Copy the URL for the repository.
+#. If the Ansys Python Manager and the **Administrator** window are not
+ open, open them. For more information, see :ref:`Ansys_Python_Manager`.
+#. In the **Administrator** window, use the ``cd`` command to go to the
+ directory where you want to clone the repository.
+
+ For example, run a command like this one::
+
+ cd C:\AnsysDev\GitRepos\PyAnsys
+
+#. Run this ``git`` command, where ```` is the URL for the repository::
+
+ git clone
+
+ For example, run a command like this one::
+
+ git clone C:\AnsysDev\GitRepos\PyAnsys\pymechanical
+
+.. _pull_from_repo:
+
+Pull changes from the main branch on GitHub
+-------------------------------------------
+
+Once you have a clone of the repository, before creating a local branch to work
+in, ensure that you have the latest codebase. Using your Git tool, pull changes
+from the remote main branch on GitHub into the main branch of your locally cloned
+repository.
+
+.. _create_local_branch:
+
+Create a local branch
+---------------------
+
+Once your clone of the repository is up to date, use your Git tool to create a local
+branch to make changes in. For changes related to documentation, your branch name
+should begin with ``doc/`` followed by a descriptive name. For example, you might
+name your branch ``doc/overall_review`` if that describes your suggested changes.
+You might name your branch ``doc/hfss_py_edits`` if your are suggesting changes
+to that particular PY file. For more information on naming branches, see
+:ref:`branch_naming`.
+
+.. _commits_pulls:
+
+Commit local changes and pull remote changes
+--------------------------------------------
+
+As you work in your local branch, periodically commit your changes and
+pull changes from the remote main branch to ensure that no changes
+there conflict with changes that you have made in your local branch. If conflicts do exist,
+resolve them in your local branch before pushing your changes to a PR.
+
+.. _push_changes:
+
+Push changes to a PR
+--------------------
+
+When you are ready to push your changes to a PR, first pull changes again
+from the remote main branch to your local branch. Providing that there are no
+conflicts to resolve, push your changes to create a PR or add to an existing
+PR. For more information, see :ref:`create_pr`. Ensure that all checks run by
+the CI/CD process are successful. If any checks fail, see :ref:`resolve_failing_checks`.
diff --git a/doc/source/content-writing/content-how-tos/create-PR.rst b/doc/source/content-writing/content-how-tos/create-PR.rst
new file mode 100644
index 000000000..506827d43
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/create-PR.rst
@@ -0,0 +1,461 @@
+.. _create_pr:
+
+Create a PR
+===========
+
+This page describes how to create a PR to update or enhance PyAnsys documentation.
+If you have not yet cloned the repository and created a local branch to work in,
+see :ref:`clone_branch`.
+
+Make changes in your local branch
+---------------------------------
+
+In your local branch, make changes to RST and PY files to improve the
+PyAnsys documentation. As you work, periodically run the tools described in the
+next few topics to check your changes. You should also periodically build the
+documentation locally so that you can verify if new or changed content is
+rendered correctly.
+
+As you work, remember to use your preferred Git tool to periodically commit your changes
+and pull merged changes from the remote main branch into your local branch. Because
+resolving conflicts is always painful, you want to do all that you can to minimize
+the possible occurrence of conflicts and resolve any that do arise locally.
+
+.. _run_precommit:
+
+Run pre-commit locally
+----------------------
+
+`pre-commit `_ is a tool for ensuring that all the changes that you make to
+files in a project successfully pass all checks run by the code style tools that are
+configured as part of the CI/CD process. These tools, which typically include `Black `_,
+`isort `_, and `Flake8 `_, analyze, format, review, and improve
+code quality and security. For more information on the code style tools most commonly
+used in PyAnsys projects, see :ref:`code_style_tools`.
+
+Because you do not want the **Code style** check for your PyAnsys project to fail
+when you create or push changes to a PR, you want to periodically run ``pre-commit``
+locally to proactively check if your changes are compliant. This tool resolves most
+code style issues automatically and adds any files it changes to Git's commit list.
+
+To run pre-commit locally:
+
+#. If the Ansys Python Manager and **Administrator** window are not still
+ open, then open them. For more information, see :ref:`Ansys_Python_Manager`.
+
+#. In the **Administrator** window, run this command::
+
+ pre-commit run --all-files
+
+ ``pre-commit`` initializes the code style tools configured for your PyAnsys project
+ if this is the first time that you are running it in this session. It then shows
+ status information for the various checks.
+
+#. In the Windows **Administrator** window, press the up arrow to display
+ the command for running ``pre-commit`` again and then run it to see if
+ all issues have been automatically resolved.
+
+ For issues that ``pre-commit`` could not automatically resolve, such as those
+ found by the ``codespell`` check, it tells you where the issues are so that you
+ can manually resolve them. Here are some issues that you might have to resolve:
+
+ - An occurrence of a spelling error or an unrecognized word
+ - A line of code that exceeds the maximum line length
+ - A failure when creating a cross reference to find the target title or caption
+ - A formatting error such as this one::
+
+ Explicit markup ends with a blank line; unexpected indent.
+
+ You can configure ``codespell`` to ignore words that it flags as errors in PY files by adding one
+ of two arguments to the ``codespell`` hook in the :file:`pre-commit-config.yaml` file in the
+ repository's root directory.
+
+ - To have ``codespell`` ignore words that you place in a TXT file named :file:`ignore_words.txt`
+ in the repositority's root directory, add this argument to the ``codespell`` hook::
+
+ hooks:
+ - id: codespell
+ args: ["--ignore-words=ignore_words.txt"]
+
+ - To have ``codespell`` accept words that you place in the :file:`accept.txt` file for
+ Vale, which is described in the next topic, add this argument to the ``codespell`` hook::
+
+ hooks:
+ - id: codespell
+ args: ["--ignore-words", "doc/styles/Vocab/ANSYS/accept.txt"]
+
+#. Manually resolve any issues that ``pre-commit`` could not resolve. For more information,
+ see :ref:`resolve_failing_checks`.
+
+#. In the Windows **Administrator** window, press the up arrow to display
+ the command for running ``pre-commit`` again and then run it.
+
+#. Resolve any issues, repeating these last few steps until ``pre-commit``
+ shows that all code style checks have passed.
+
+.. _run_Vale_locally:
+
+Run Vale locally
+----------------
+
+`Vale `_ is a tool for maintaining a consistent style and voice in your
+documentation based on a given style guide. For PyAnsys projects, Vale
+uses rules from the `Google developer documentation style guide `_
+to check the content in RST and MD files. In addition to checking for style guide violations,
+Vale checks for other common problems, such as extra spaces, repeated words, excessive use of
+jargon, sexist language, and incorrect capitalization. Vale does not check the content surrounded
+in double backticks or in code blocks.
+
+When Vale detects an issue, it displays a suggestion, warning, or error. While you can choose
+to ignore a suggestion or warning, you must resolve all errors. Otherwise, when you
+create or push changes to a PR, the **Vale** check fails, which also causes the
+**Documentation style** check to fail.
+
+Because you do not want these checks to fail on the PR, you want to periodically run Vale
+locally to proactively check that your changes are compliant.
+
+To run Vale locally:
+
+#. If the Ansys Python Manager and **Administrator** window are not still
+ open, open them. For more information, see :ref:`Ansys_Python_Manager`.
+#. From the Windows **Administrator** window, use the ``cd`` command to go to the
+ library's ``doc`` directory.
+
+ For example, to go to the ``doc`` directory for this guide, you might
+ run this ``cd`` command:
+
+ .. code-block:: bash
+
+ cd C:\AnsysDev\GitRepos\PyAnsys\pyansys-dev-guide\doc
+
+#. To ensure that the latest rules for the Google style guidelines are installed
+ locally, run this command:
+
+ .. code-block:: bash
+
+ vale sync
+
+ .. note::
+ The preceding command downloads the latest rules for the
+ *Google developer's documentation style guide* to the ``doc/styles/Google``
+ folder. If the :file:`.gitignore` file in your project's root directory is not
+ set up to ignore these YML style files, add the following lines to the end of
+ this file:
+
+ .. code-block:: bash
+
+ # Vale
+ doc/styles/Google
+
+ \#*
+ .\#*
+ /.ipynb_checkpoints
+
+ The next several steps show how to use various Vale commands to check RST and MD
+ files in different directories.
+
+#. To check all RST and MD files in the ``doc`` directory, run this command:
+
+ .. code-block:: bash
+
+ vale .
+
+ If Vale displays errors in ``build\html\_static\404.rst``, it is checking files generated
+ by a previous local build of the documentation. Delete the ``html`` directory and
+ then run the preceding command again.
+
+#. To check all RST and MD files in the repository, go to the root directory and
+ run this command:
+
+ .. code-block:: bash
+
+ vale --config=doc/.vale.ini .
+
+#. To check all RST and MD files in only a particular directory, start the command
+ with ``vale`` followed a space and then the name of the directory.
+
+#. To resolve errors and other issues that Vale raises, either edit files or
+ add words or phrases to the ``accept.txt`` file in ``doc\styles\Vocab\ANSYS``.
+
+Here is an explanation of how Vale is set up in a PyAnsys project. The ``doc`` directory
+contains the ``.vale.ini`` configuration file and the ``styles`` directory.
+
+- The ``.vale.ini`` configuration file specifies that Vale is to check content
+ in RST and MD files to ensure that it is compliant with the
+ *Google developer documentation style guide*, along with any custom Ansys rules.
+
+- In the ``styles`` directory, the ``Vocab/ANSYS`` directory contains ``accept.txt``
+ and ``reject.txt`` files. You can add words or phrases that Vale does not recognize
+ to the ``accept.txt`` file, and you can add recognized words or phrases that you want
+ Vale to raise as issues to the ``reject.txt`` file.
+
+Vale is case-aware. When adding words to the ``accept.txt`` file, use an appropriate
+regular express if an entry should be case-insensitive.
+
+- To make an entire word case-insensitive, use a ``(?i)`` prefix. For example,
+ add ``(?i)Ansys`` to have Vale accept "Ansys," "ANSYS," and "ansys."
+- To make it acceptable for a word to start in either uppercase or lowercase, place
+ both cases of the first letter in brackets. For example, add ``[Dd]ocstrings``.
+
+Occasionally Vale raises issues that are not considered errors in PyAnsys
+projects. For more information, see :ref:`work_around_Vale_issues`.
+
+.. note::
+ If Vale raises a runtime error when running locally, the error indicates the
+ file where the issue exists. In all likelihood, the file has two links that use
+ the same display text to the same named target. Modifying the display text for one
+ of the two links should resolve the issue.
+
+.. _pull_changes_from_main:
+
+Build documentation locally
+---------------------------
+
+`Sphinx `_ is a tool for generating documentation. While designed primarily for
+generating documentation for Python projects, it can be used for documenting other programming
+languages and projects.
+
+The build process for a project's documentation is specified in a configuration (:file:`conf.py`)
+file in the ``doc/source`` directory. This directory also contains a :file:`Makefile` file and a
+:file:`make.bat` file for automating the building process. Different builders render different
+documentation output, such as ``HTML``, ``LaTeX``, or ``PDF``.
+
+When making lots of changes, consider building the HTML documentation locally so that you can
+see if your changes are rendered correctly. Otherwise, you can download and view the documentation
+artifacts that are built by the pipeline's :file:`ci-build.yml` file once the **Documentation building**
+check on the PR passes. For more information, see :ref:`view_artifacts`.
+
+To build documentation locally:
+
+#. If the Ansys Python Manager and **Administrator** window are not still
+ open, open them. For more information, see :ref:`Ansys_Python_Manager`.
+#. From the Windows **Administrator** window, use the ``cd`` command to go to the
+ library's ``doc`` directory.
+
+ For example, to go to the ``doc`` directory for this guide, you might
+ run this ``cd`` command:
+
+ .. code-block:: text
+
+ cd C:\AnsysDev\GitRepos\PyAnsys\pyansys-dev-guide\doc
+
+#. Run the ``make`` command for you operating system.
+
+ - On Windows, run ``make.bat html``.
+ - On Linux or macOS, run ``make html``.
+
+ The resulting HTML files are created in the project's ``doc/_build/html`` directory by default.
+
+#. To view the HTML documentation, use your favorite browser to open the ``index.html`` file:
+
+ .. code-block:: text
+
+ .doc/_build/html/index.html
+
+If a project's CI/CD process uses `tox `_ for testing and task automation, rather than
+using the Sphinx documentation-building method, check the integrity of the documentation
+by running this command locally:
+
+.. code-block:: text
+
+ tox -e doc
+
+``tox`` places the resulting HTML files in the project's ``.tox/doc_out`` directory by default.
+To view the HTML documentation, use your favorite browser to open the ``index.html`` file in
+this directory:
+
+.. code-block:: text
+
+ .tox/doc_out_html/index.html
+
+If you would like ``tox`` to place the resulting HTML files in the project's ``doc/_build/html`` directory,
+you can replace the last two lines in the :file:`tox.ini` file with these two lines:
+
+.. code-block:: text
+
+ commands =
+ sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxinidir}/doc/_build/html" --color -vW -b html -j auto
+
+Create a PR
+-----------
+
+Before you use your Git tool to push your changes to a PR, first use it to pull merged changes
+from the remote main branch to your local branch. If there are any conflicts, resolve
+them in your local branch.
+
+To create a PR:
+
+#. Use your Git tool to push your changes to the remote main branch.
+
+ On the main page of the repository, a notification indicates that a branch had recent pushes.
+
+ .. image:: ..//_static/notice-recent-pushes.png
+ :alt: Recent pushes notification
+
+#. Click **Compare & pull request**.
+ The **Open a pull request** window opens.
+#. Supply a commit message and an optional extended description.
+#. Click **Create pull request**. Or, if you want to create a draft pull request,
+ use the dropdown to select **Create draft pull request**.
+
+ A draft pull request cannot be merged until you mark it as ready for review,
+
+.. tip::
+ The `Ansys Review Bot `_ can perform a review of your changes. For more information,
+ see :ref:`bot_reviews`.
+
+Resolve failed checks
+---------------------
+
+GitHub integrates with tools that automate code and documentation style
+checking, testing, and deployment, which makes it far easier to streamline the development
+process and maintain high code quality. When you create or submit changes to a PR, all checks that
+are configured in the project's CI/CD process run. When a check fails, you must resolve the issues causing
+the failure. For more information, see :ref:`resolve_failing_checks`.
+
+.. _view_artifacts:
+
+Download and view documentation artifacts
+-----------------------------------------
+
+If the **Documentation building** check on the PR completes successfully, both HTML and PDF
+documentation artifacts are generated:
+
+- ``documentation-html``
+- ``documentation-pdf``
+
+You can download and unzip these artifacts to see how the documentation for this PR is
+rendered. While you generally do not need to download the PDF artifact, you should
+download and extract the HTML artifact so that you can confirm that the changes in the PR
+render correctly in the documentation.
+
+To download and view documentation artifacts:
+
+#. On the repository's **Actions** page, click the GitHub CI workflow run for your pull request.
+#. Under **Artifacts**, which is at the bottom of the page, click the artifacts to download.
+
+ As mentioned earlier, you likely only want to download the ``documentation-html`` artifact.
+
+#. Go to your ``Downloads`` folder and use a tool like `7-Zip `_ to extract the HTML
+ artifact (and PDF artifact if you also downloaded it).
+#. To view the generated HTML documentation, in the folder that you extracted this artifact's
+ files to, double-click the :file:`index.html` file to open the HTML documentation.
+#. To view the generated PDF documentation, in the folder that you extracted this artifact's file
+ to, double-click the PDF file to open it.
+
+.. note::
+ The artifacts for a PR are only available if the **Documentation building** check completed
+ successfully. If you click the GitHub CI workflow run for a PR where this check failed,
+ no artifacts are shown under **Artifacts**. Artifacts remain available after PRs are
+ merged.
+
+Tag reviewers
+-------------
+
+In the PR, the right pane of the **Conversation** page displays a **Reviewers** area. In many
+PyAnsys projects, maintainers are automatically assigned as reviewers. You can manually
+assign any number of reviewers. You can also see how many approving reviewers are
+required before the PR can be merged. This number varies from one PyAnsys project to another.
+
+Manually add reviewers to your PR:
+
+#. Click the gear icon on the right side of this area.
+#. Choose the reviewer to add.
+
+If a specified number of maintainers must review and approve the PR, the PR displays a
+**Code owner review required** area with status information.
+
+.. tip::
+ You can add comments to your own PR as indicated in :ref:`add_comments` and then
+ resolve them as indicated in the next topic. If you intend to keep working in
+ your local branch, remember to always use your Git tool to pull all changes made
+ in the remote branch for your PR into your local branch.
+
+.. _resolve_reviewer_comments:
+
+Resolve reviewer comments
+-------------------------
+
+A reviewer can make a general comment on your overall PR and both general and specific
+comments on a single changed line or multiple consecutive changed lines in
+your PR. For more information, see :ref:`add_comments` in the information for reviewing
+a PR.
+
+The **Conversation** page of your PR shows all overall comments on your PR and all
+unresolved comments on changed lines in your PR. Because overall comments are informational,
+they do not display ``Resolve conversation`` buttons. However, all unresolved comments on
+changed lines do display this button.
+
+Here is how to review and resolve comments on changed lines:
+
+#. On the **Conversation** page, determine whether the comment requires you to
+ make changes to one or more files in your local branch.
+
+ - If the comment is merely informational, click ``Resolve conversation``.
+ - If you must make changes in your local branch, do not click ``Resolve conversation``.
+
+ Instead, make these changes and push them to the PR.
+
+#. If the comment makes changes to one or more lines, determine if you want
+ to commit the suggestion.
+
+ .. note::
+ If you click **Commit suggestion** on a reviewer's suggestion and then
+ click **Commit changes** in the window that opens, the suggestion is
+ immediately committed to the PR, which triggers a build. Because the CI/CD
+ process is resource intensive, best practice is to commit suggestions in batch,
+ which triggers the build process only once. Subsequent steps assume that you
+ are following this best practice.
+
+#. To commit the suggestion, click **Add suggestion to batch**.
+#. Repeat the preceding steps to review and resolve comments or commit suggestions.
+
+ At the top of the PR, the **Commit suggestions** option indicates
+ the number of suggestions that are waiting to be committed in batch.
+
+#. When you are ready to commit all suggestions in batch, click
+ **Commit suggestions** at the top of the PR and, in the window that opens,
+ click **Commit Changes**.
+
+#. If you intend to keep working in your local branch, use your Git tool
+ to pull all changes made in the remote branch for your PR into your local branch.
+
+GitHub notifies you if there are any merge conflicts. You can use the GitHub editor
+to find and edit the conflicts.
+
+Merge your PR
+-------------
+
+You can merge your PR only after these criteria are met:
+
+- All required reviewers have approved the PR.
+- All conversations in the PR are resolved.
+- All checks configured in the CI/CD process have passed.
+- The branch has no conflicts with the base branch.
+
+.. note::
+ If the branch is out of date with the remote main branch, merging is blocked.
+ To the right of the **This branch is out-of-date with the base branch**
+ notification is an **Update branch** option. Clicking it merges the latest
+ changes in the main branch into this branch with a merge commit. While the
+ dropdown provides an option for rebasing this PR on top of the latest changes
+ and then force pushing the PR, choosing this option is not advised.
+
+When these criteria are met, a required reviewer might merge the PR for you.
+If not, you can merge the PR:
+
+#. Click the **Squash and merge** option.
+#. In the window that opens, provide an optional extended description and
+ click **Confirm squash and merge**.
+
+.. tip::
+ When you finish resolving comments, you can click the **Enable auto-merge (squash)** option
+ to have PR be automatically merged when all criteria are met.
+
+Pull changes and delete the merged branch
+-----------------------------------------
+
+One the PR is merged, use your GitHub tool to pull all changes from the remote main
+branch on GitHub into the main branch of your locally cloned repository. Also delete
+the local branch with the changes that have now been merged. For additional changes,
+create another local branch to work in.
diff --git a/doc/source/content-writing/content-how-tos/create-issues-discussions.rst b/doc/source/content-writing/content-how-tos/create-issues-discussions.rst
new file mode 100644
index 000000000..98dc160c7
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/create-issues-discussions.rst
@@ -0,0 +1,75 @@
+.. _issues_discussions:
+
+Create issues and discussions
+=============================
+
+Content contributors can be active participants in enhancing and adding to PyAnsys libraries.
+In addition to reviewing and creating PRs, you can create issues and discussions
+on the **Issues** page and **Discussions** page of a GitHub repository.
+
+- Issues report, track, and manage bugs, feature requests, and other project-related
+ tasks. Issues help to organize development efforts and prioritize work. Once an
+ issue is created, you and others can leave comments to provide additional information,
+ solutions, and progress updates.
+
+- Discussions foster communication and interaction among community members, contributors,
+ and project maintainers. Discussions help to centralize conversations on particular topics,
+ such as general usage questions or product announcements. You can also use discussions to
+ facilitate brainstorming, planning, and the gathering of feedback.
+
+Create an issue
+---------------
+
+To report an issue, request a new feature, or ask for troubleshooting assistance, create
+an issue in the project's repository:
+
+#. Go to the project repository.
+#. Click the **Issues** tab to go to the **Issues** page.
+#. In the upper right corner, click **New Issue**.
+#. If the page that opens lists templates, click **Get Started** for the
+ appropriate template.
+
+ In most repositories, these issue templates are available:
+
+ - **Bug, problem, error**: For filing a bug report
+ - **Documentation issue**: For requesting modifications to the documentation
+ - **Adding an example for Python project**: For proposing a new example for a client library
+ - **New feature**: For requesting enhancements to the code
+
+ If your issue does not fit one of these templates, you can click the **Open a blank issue**
+ link.
+
+#. Complete the form that is shown, providing a clear and detailed description of the issue. Include
+ any relevant error messages, code snippets, and screenshots.
+#. Click **Submit new issue**.
+
+To contact the project support team about an issue, email `pyansys.core@ansys.com `_.
+
+Create a discussion
+-------------------
+To post questions, share ideas, and get community feedback, create a discussion in
+the project's repository:
+
+#. Go to the project repository.
+#. Click the **Discussions** tab to go to the **Discussions** page.
+
+ .. note::
+ In some repositories, the **Discussions** page is not available because the
+ project maintainers want you to always use the `Discussions `_
+ page on the Ansys Developer portal instead.
+
+#. In the upper right corner, click **New discussion**.
+#. If the page that opens lists templates, click **Get Started** for the
+ appropriate template.
+
+ In most repositories, these discussion templates are available:
+
+ - **Announcements**: For filing a bug report
+ - **General**: For chatting about anything and everything
+ - **Ideas**: For sharing ideas for new features
+ - **Polls**: For taking a vote from the community
+ - **Q&A**: For asking the community for help
+ - **Show and tell**: For showing off something that you've made
+
+#. Complete the form, providing a clear and detailed title and description.
+#. Click **Start discussion**.
\ No newline at end of file
diff --git a/doc/source/content-writing/content-how-tos/edit-on-GitHub.rst b/doc/source/content-writing/content-how-tos/edit-on-GitHub.rst
new file mode 100644
index 000000000..ac142d945
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/edit-on-GitHub.rst
@@ -0,0 +1,47 @@
+.. _edit_on_GitHub:
+
+Edit on GitHub
+==============
+
+The easiest way to contribute to a PyAnsys project is to make changes in GitHub,
+letting the CI/CD process handle the build. When you are viewing PyAnsys
+documentation, the right navigation pane might display an **Edit on GitHub** link.
+You can use this feature to submit changes to this page via a PR on GitHub:
+
+#. Click the **Edit on GitHub** link.
+
+ The GitHub web editor opens with the **Edit** tab active by default.
+ You can search within the file using **ctrl+F**.
+
+#. Make suggested changes to the file.
+#. When finished, in the top right corner of the window, click **Commit
+ changes**.
+
+ The **Propose changes** window opens.
+
+#. Supply a commit message and an optional extended description.
+#. Because you must create a new branch for committing this suggestion
+ and creating the PR, supply a branch name.
+
+ For PRs related to documentation, your branch name should begin with
+ ``doc/`` followed by a descriptive name. For example, you might supply
+ ``doc/fix_broken_link`` if that is what your suggested change does. For
+ more information, see :ref:`branch_naming`.
+
+#. Click **Propose changes**.
+
+The PR is created, and the checks configured by the CI/CD process run. Your next
+steps are basically the same as if you had created the PR from a cloned copy of
+the repository:
+
+#. Resolve failed checks.
+#. Download and view documentation artifacts.
+#. Tag reviewers.
+#. Resolve reviewer comments.
+#. Merge your PR.
+
+For more information, see :ref:`create_pr`.
+
+.. tip::
+ If you need to make changes to other files as part of this PR, you can use
+ your preferred GitHub tool to check out the branch and work in it.
diff --git a/doc/source/content-writing/content-how-tos/index.rst b/doc/source/content-writing/content-how-tos/index.rst
new file mode 100644
index 000000000..493fbb7ca
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/index.rst
@@ -0,0 +1,36 @@
+.. _content_how_tos:
+
+Content how-tos
+===============
+
+This section describes how to perform tasks related to contributing
+to PyAnsys documentation. As indicated in earlier sections, PRs suggest
+changes to the main codebase. Each PR undergoes a thorough review before
+it can be approved and subsequently merged into the codebase.
+
+Content contributors typically contribute to the codebase for a PyAnsys
+library in one of two ways:
+
+- By reviewing PRs created by fellow contributors
+- By creating PRs that add to or improve the documentation
+
+Additionally, content contributors can create issues on the **Issues**
+page of a library's GitHub repository. If the repository has a **Discussions**
+page, they can use it to start a discussion on this library. Otherwise, you
+can post questions, share ideas, and get community feedback on the
+`Discussions `_ on the Ansys Developer portal.
+
+.. toctree::
+ :maxdepth: 3
+ :hidden:
+
+ clone-branch
+ review-PR
+ create-PR
+ request-bot-review
+ work-around-Vale
+ resolve-issues-causing-check-failures
+ edit-on-GitHub
+ view-revision-history
+ add-sphinx-extensions
+ create-issues-discussions
diff --git a/doc/source/content-writing/content-how-tos/request-bot-review.rst b/doc/source/content-writing/content-how-tos/request-bot-review.rst
new file mode 100644
index 000000000..1777c1eb1
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/request-bot-review.rst
@@ -0,0 +1,41 @@
+.. _bot_reviews:
+
+Request a bot review
+====================
+
+You can have the `Ansys Review Bot `_ perform a review of your changes.
+If this bot is already turned on in your project, this comment from the bot
+displays on the **Conversation** page of the PR::
+
+ Thanks for opening a Pull Request. If you want to perform a review write a
+ comment saying:
+
+ @ansys-reviewer-bot review
+
+.. note::
+ If your project is in the Ansys internal account, the comment that you write
+ is ``@ansys-internal-reviewer-bot review``. This topic assumes that you
+ write ``@ansys-reviewer-bot review`` because your project is public.
+
+If you do not see a comment from the bot but want to use it, email
+`pyansys.core@ansys.com `_ to request that they turn
+the bot on in your project.
+
+To use the bot:
+
+#. Copy ``@ansys-reviewer-bot review`` from the bot's comment.
+#. Scroll to the bottom of the page, paste this comment in the **Write** tab, and click **Comment**.
+
+ The bot responds with this comment::
+
+ Okay, I will trigger a review of your PR.
+
+ Depending on how large your PR is, it may take a few minutes before comments
+ from the bot begin to appear. If comments never appear, the bot service has
+ likely stopped responding. You can email `pyansys.core@ansys.com `_
+ to request that they restart the service.
+
+#. Resolve bot comments just like you resolve other reviewer comments. For more
+ information, see :ref:`resolve_reviewer_comments`.
+
+You can run the bot again when you next push changes to the PR.
diff --git a/doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst b/doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst
new file mode 100644
index 000000000..6fa399e93
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst
@@ -0,0 +1,196 @@
+.. _resolve_failing_checks:
+
+Resolve issues causing check failures
+=====================================
+
+All checks in the CI/CD process must pass before a PR can be approved and
+merged. Even if you remember to run ``pre-commit`` and Vale locally and resolve
+all issues, when you push your changes to the PR, checks in the CI/CD process
+can still fail.
+
+For information on continuous integration and the required workflows that run
+checks on a PR for a PyAnsys library, see :ref:`continuous_integration`.
+
+When a check in the CI/CD process fails, you can click **Details** to the right
+of the check to view its log. You are taken to the bottom of the log, where you can see
+the total number of warnings and errors.
+
+While you can scroll the log to find these warnings and errors, the log can be quite
+long. Use the **Search logs** option in the upper right of the window to search
+first for ``warning`` and then for ``error``. (This sequence is recommended because
+warnings and errors are often related.)
+
+The first occurrence of ``warning`` in the log is a hint about how to suppress a
+warning about the name of the initial branch of the repository. This is not
+a warning included in the count to resolve and can be safely ignored. Subsequent
+occurrences of ``warning``, and then ``error``, reveal the issues, with the filenames
+and lines where you must resolve them.
+
+Your objective should always be to eliminate or mitigate issues before creating
+or pushing changes to a PR. For example, running ``pre-commit`` and Vale locally
+allows you to proactively resolve typos and trailing whitespaces. However,
+oftentimes, you must resolve issues that cause the checks run by the CI/CD
+process to fail.
+
+Resolve typos
+-------------
+
+In PyAnsys projects, two tools in the CI/CD process check for typos,
+`codespell `_ and `Vale `_. ``codespell`` is one
+of the code style tools that ``pre-commit`` is configured to run. If
+you always run ``pre-commit`` and ``Vale`` before creating or
+pushing changes to a PR, these two checks in the CI/CD process
+should not fail.
+
+- For more information, see :ref:`run_precommit`.
+- For more information, see :ref:`run_Vale_locally`.
+
+.. note::
+ If the **Vale** check on a PR fails, the **Documentation style** check also
+ fails. Resolving the Vale issues might be all you need to do to get
+ the **Documentation style** check to pass successfully.
+
+Resolve trailing whitespaces
+----------------------------
+
+If you forget to run ``pre-commit`` locally, when you create or push
+changes to a PR, the CI/CD process is likely to raise errors about
+trailing whitespaces. Rather than locating and resolving these errors manually,
+run ``pre-commit`` locally to have it find and automatically trim these trailing
+whitespaces for you. Then, commit and push the files that ``pre-commit`` has modified
+to the PR.
+
+Resolve formatting issues
+-------------------------
+
+When you push changes to a PR, you might see one of the documentation checks fail,
+even if you ran ``pre-commit`` locally and all configured tools ran successfully.
+Documentation check failures are usually the result of formatting issues and
+incorrect links, resulting in warnings and errors like these:
+
+.. code::
+
+ WARNING: Inline emphasis start-string without end-string.
+ WARNING: Inline literal start-string without end-string.
+ WARNING: document isn't included in any toctree
+ WARNING: Literal block ends without a blank line; unexpected unindent.
+ WARNING: Enumerated list ends without a blank line, unexpected unindent.
+ WARNING: undefined label: 'py_file_formatting'
+ WARNING: Duplicate explicit target name: "py_code_comments".
+ ERROR: Unexpected indentation.
+ ERROR: Unknown interpreted text role "files".
+ ERROR: Indirect hyperlink target "numpydoc docstrings" refers to target "dev_guide_numpy_docstrings", which does not exist.
+ ERROR: Unknown target name: "dev_guide_numpy_docstrings".
+
+
+For each warning and error, a filename and line is indicated. You must go to these
+locations and make the changes necessary to resolve the warnings and errors.
+Actions that you might take include these:
+
+- Add missing start or end strings to various types of format tags.
+- Add a new RST file to the appropriate :file:`index.rst` file.
+- Indent all lines in a literal block correctly.
+- Add blank lines both before and after a list or literal block.
+- Correct links to internal labels and external targets.
+
+
+.. _resolve_too_long_lines_broken_links:
+
+Resolve too long line lengths and broken links
+----------------------------------------------
+
+In PyAnsys projects, `Flake8 `_ is a code style tool in the CI/CD process
+that checks the quality of the Python code. When you run ``pre-commit`` locally,
+Flake8 is one of the tools that it is configured to run. If Flake8 finds a line in a
+Python file that is too long, it raises an error. Providing that this line is a
+docstring or message string, you can manually change it in the PY file.
+
+Sometimes, however, the line that is too long is for a URL added to the ``linkcheck_ignore``
+variable in the Sphinx configuration (``doc/source/conf.py``) file. Here is an example of how
+this can happen. The central links (``doc/source/links.rst``) file for this guide contains
+explicit target names for joining the two Ansys GitHub accounts:
+
+.. code::
+
+ .. _join_ansys_organization: https://myapps.microsoft.com/signin/8f67c59b-83ac-4318-ae96-f0588382ddc0?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706
+ .. _join_ansys_internal_organization: https://myapps.microsoft.com/signin/42c0fa04-03f2-4407-865e-103af6973dae?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706
+
+When building documentation, Sphinx checks all links to ensure that they are valid. In most cases,
+broken links are the result of formatting errors that you must fix manually. However, the
+URLs for the preceding targets are behind firewall rules. Because Sphinx is unable to validate these links,
+it indicates that they are broken.
+
+Because Sphinx is also unable to validate the ``38-comments-and-docstrings``
+anchor in the following named target to a section in the *Google Python Style Guide*, it identifies it as broken:
+
+.. code::
+
+ .. _Google_docstrings: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
+
+To resolve links that are identified as broken because they are behind firewall rules, you must add the
+URLs (and any comments about these URLs) to the ``linkcheck_ignore`` variable in the Sphinx
+:file:`config.py` file. To resolve links with anchors that are identified as broken, you must
+add the anchor to the ``linkcheck_anchors_ignore`` variable in the Sphinx :file:`config.py` file.
+
+Here is what adding these lines looks like:
+
+.. code::
+
+ # Linkcheck ignore too long lines
+
+ linkcheck_ignore = [
+ "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",
+ ]
+
+If you committed the preceding changes, Sphinx would no longer find any broken links. However, Flake8
+would throw line length errors for the two lines that define the items for the ``linkcheck_ignore`` variable
+in the Sphinx :file:`config.py` file. Because you cannot modify the length of these lines, you must follow
+each of these URLs (and any comment about it) with a space and then ``# noqa: 501``.
+
+You can scroll to the end of these lines to see how they now conclude with ``# noqa: 501``:
+
+.. code::
+
+ # Linkcheck ignore too long lines
+
+ linkcheck_ignore = [
+ "https://myapps.microsoft.com/signin/8f67c59b-83ac-4318-ae96-f0588382ddc0?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706", # Join Ansys GitHub account # noqa: 501
+ "https://myapps.microsoft.com/signin/42c0fa04-03f2-4407-865e-103af6973dae?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706", # Join Ansys internal GitHub account # noqa: 501
+ ]
+
+When you commit these changes, Flake sees the ``# noqa: 501`` comments at the end of these lines
+and knows to ignore their long line lengths.
+
+.. _resolve_mismatched_message_strings:
+
+Resolve mismatched message strings
+----------------------------------
+
+As indicated in :ref:`py_message_strings`, you want to ensure that the message
+strings in PY files provide clear and understandable information or instructions
+to users. Sometimes, editing a message string can cause a test on the PR to fail.
+This occurs when a test checks for the occurrence of a particular message string,
+but this message string is no longer found in the PY file.
+
+When a test on a PR fails, you can click ``Details`` to the right of this test to
+see the log. An error indicates that the message string in the test does not match
+a message string in the PY file.
+
+.. tip::
+ To quickly find the error, you can use the **Search logs** option in the
+ upper right of the window to search for ``match=``.
+
+To resolve the error, you must open the indicated test file and edit the message
+string in it to match the message string in the PY file.
+
+.. todo::
+ Find a test failure due to a message string mismatch to possible include an
+ example and ensure the the information provided in this topic is correct.
diff --git a/doc/source/content-writing/content-how-tos/review-PR.rst b/doc/source/content-writing/content-how-tos/review-PR.rst
new file mode 100644
index 000000000..37e9b7de5
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/review-PR.rst
@@ -0,0 +1,120 @@
+.. _review_pr:
+
+Review a PR
+===========
+
+This page describes how to review a PR created by someone else. The
+next page describes how to create your own PR.
+
+When someone wants you to review a PR, this person generally tags you as a
+reviewer on the PR. In the GitHub notification you receive, you can click the
+link to go to the PR.
+
+The simplest way to learn how to contribute to a project is to begin reviewing
+PRs that other contributors have created. You can add suggestions in their PRs
+for improving content, thereby build the confidence that you need to create your
+own PRs.
+
+Being an effective reviewer assumes that you are familiar with all the
+resources listed in :ref:`resources_writers`.
+
+.. _add_comments:
+
+Add a comment
+-------------
+
+On the **Conversation** page of the PR, you can add a general comment on the
+overall PR by scrolling to the bottom of the page, entering your comment in
+the **Write** tab, and clicking **Comment**.
+
+On the **Files changed** page of the PR, you can add a general comment on
+a single changed line or multiple consecutive changed lines in a file. You can
+also add a comment that suggests specific changes to a single line or multiple
+consecutive lines.
+
+If the PR includes changes to multiple files, the **Files changed** page has
+two panes. The left pane displays a list of all changed files, and the right pane
+displays the files themselves, with changes highlighted in green. To quickly
+see the changes made to a particular file, click its entry in the left pane.
+
+.. _add_comment_on_line:
+
+Add a general comment on a line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add a general comment on a line:
+
+#. Click the plus sign to the right of the line number.
+
+ .. image:: ..//_static/GitHub-line-selector-suggestions.png
+ :alt: Line selector
+
+#. In the window that opens, type your comment.
+#. Click **Add single comment** to add your comment and close the window.
+
+Add a comment suggesting a change to a single line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add a comment suggesting a change to a single line:
+
+#. Click the plus sign to the right of the line number.
+#. In the window that opens, click the **Add a suggestion** icon:
+
+ .. image:: ..//_static/icon-add-suggestion.png
+ :alt: Add a suggestion icon
+
+ GitHub copies the content of line, placing it in a ``suggestion`` tag in the
+ window's **Write** tab. The suggestion tag begins and ends with triple
+ backticks (:code:`\`\`\``) like this::
+
+ ```suggestion
+ This test shows how composite data can be stored.
+ ```
+
+
+#. Within the ``suggestion`` tag, edit the content to reflect your suggested
+ changes.
+#. If you want to provide any information about your suggested change, type it
+ directly under the three backticks that close the ``suggestion`` tag::
+
+ ```suggestion
+ This test shows how composite data can be stored.
+ ```
+ Here is were you type information about your suggested change.
+
+#. Click **Add single comment** to add your comment and close the window.
+
+Add a comment suggesting changes to multiple lines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add a comment suggesting changes to multiple consecutive lines:
+
+#. Click the plus sign to the right of the first line number that you want to comment on
+ and then drag the mouse to the last line number you want to comment on before
+ releasing the mouse button.
+
+ The selected lines are highlighted in yellow.
+
+#. In the window that opens, click the **Add a suggestion** icon.
+
+ GitHub places the content of the selected lines within a ``suggestion`` tag in
+ the window's **Write** tab.
+
+#. Within the ``suggestion`` tag, edit the content to reflect your suggested
+ changes.
+#. If you want to provide a comment about your suggested changes, type it
+ directly under the three backticks that close the ``suggestion`` tag.
+#. Click **Add single comment** to add your comment and close the window.
+
+Submit your review
+------------------
+
+When you finish reviewing the PR, submit your review:
+
+#. In the upper right corner of the GitHub window, click **Review changes** .
+
+ The **Finish your review** window opens.
+
+#. Leave a comment about your review.
+#. Choose the **Comment**, **Approve**, or **Request changes** option.
+#. Click **Submit review**.
diff --git a/doc/source/content-writing/content-how-tos/view-revision-history.rst b/doc/source/content-writing/content-how-tos/view-revision-history.rst
new file mode 100644
index 000000000..d66016cbb
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/view-revision-history.rst
@@ -0,0 +1,36 @@
+.. _View_revision_history:
+
+View revision history on GitHub
+===============================
+
+GitHub *blame* is a feature that allows you to view the revision history of a
+file in a repository to see who made changes and when these changes were
+made. You can use the GitHub blame feature for a variety of use cases, including
+these:
+
+- **Knowledge expansion**: When implementing something new or making changes in unfamiliar areas
+ of the codebase, you can use GitHub blame to see how someone else implemented or changed
+ something similar.
+- **Code review**: When reviewing code changes, you can use GitHub blame to understand why
+ specific lines were modified and by whom, making it easier to provide feedback or
+ ask questions.
+- **Debugging**: When you encounter a bug or an issue in the code, you can use GitHub blame
+ to help identify when and where a particular piece of problematic code was introduced.
+- **Accountability**: When you need to resolve disputes or track collaborations, you can use
+ GitHub blame to see who made specific changes.
+
+Here is how you use GitHub blame:
+
+#. Navigate to a specific file in a GitHub repository.
+#. To see the revision history for the entire file, click the **Blame** tab in the
+ file header.
+#. To go to the revision history for a particular line of code, on the **Code** tab,
+ click this line number, and when the box with an ellipsis (``...``) appears, click
+ this box and select **View git blame**.
+
+ This takes you to the selected line on the **Blame** tab. However, you can always
+ scroll to see the revision history for all lines in the file.
+
+On the right side, you see how long ago a change was made to the file or a specific line,
+who made the change, and the PR in which the change was made. Clicking the PR takes
+you to it so that you can view all changes made to all files in the PR.
diff --git a/doc/source/content-writing/content-how-tos/work-around-Vale.rst b/doc/source/content-writing/content-how-tos/work-around-Vale.rst
new file mode 100644
index 000000000..23ed6a25b
--- /dev/null
+++ b/doc/source/content-writing/content-how-tos/work-around-Vale.rst
@@ -0,0 +1,149 @@
+.. _work_around_Vale_issues:
+
+Work around Vale issues
+=======================
+
+Some issues that Vale raises may not be considered problematic in PyAnsys
+projects. This page describes some common workarounds.
+
+Turn Vale on and off
+--------------------
+
+If Vale flags content as an issue but you know that this content is
+acceptable, you can use the following directives to turn Vale off
+before the flagged content and then back on again after it::
+
+ .. vale off
+
+ This is some text.
+
+ .. vale on
+
+As shown in the preceding example , you must insert blank lines to separate the
+directives for tuning Vale off and off from your documentation content.
+
+In an MD file, the syntax for these two Vale directives looks like this::
+
+
+
+ This is some text.
+
+
+
+Insert non-breaking spaces
+--------------------------
+
+Vale displays a warning when it thinks a non-breaking space should be used
+in an RST or MD file. Here is how you insert a non-breaking space:
+
+- In an RST file, use the Unicode character ``U+00A0`` for a non-breaking space.
+ You can insert it by typing `` `` or `` ``.
+- In an MD file, use the HTML entity `` `` or the Unicode character ``U+00A0``
+ for a non-breaking space. You can insert it by typing `` ``.
+
+For example, you can insert a non-breaking space between two words in either an RST or
+MD file by typing ``word1 word2``.
+
+Allow the use of a word not allowed by the Google word list
+-----------------------------------------------------------
+
+Based on an implemented Google word list, Vale raises warnings when certain
+words, such as "check" and "functionality," are used. While you can ignore
+Vale warnings, if the list of warnings becomes long, it can become annoying
+to have to scroll through them to find the errors that you must address.
+
+To have Vale accept your use of a word that is raising a warning, you can
+add the word to the :file:`accept.txt` file in the ``doc/styles/Vocab/ANSYS``
+directory.
+
+Turn off a particular style rule
+--------------------------------
+
+Vale implements many Google style rules, which you can see in the YML files in
+the ``doc/styles/Google`` directory. If necessary, you can turn off a particular
+rule.
+
+For example, the rule in the :file:`Colons.yml` file specifies that a lowercase letter
+must follow a colon. However, in some cases, you might want to allow uppercase letters to
+follow colons.
+
+While you could turn Vale off and on each time an error is raised for this colon
+style violation, this approach is cumbersome if there are many such errors.
+Thus, you can turn off the Google style rule that is causing Vale to raise the
+error:
+
+#. Go the ``doc`` directory and open the :file:`vale.ini` file.
+
+#. Locate this content::
+
+ # Apply the following styles
+ BasedOnStyles = Vale, Google
+
+#. Add a line to turn off the Google rule about requiring a lowercase
+ letter after a colon::
+
+ # Apply the following styles
+ BasedOnStyles = Vale, Google
+ Google.Colons = NO
+
+Tell Vale to ignore inline roles
+--------------------------------
+
+If Vale raises errors about content within inline roles, such as ``ref``, ``file``, and ``class``,
+implement a workaround by telling Vale to ignore this content. Simply follow the previous
+steps, adding the ``TokenIgnores`` argument to the end of the :file:`vale.ini` file::
+
+ # Apply the following styles
+ BasedOnStyles = Vale, Google
+ Google.Colons = NO
+
+ # Ignore content in inline roles
+ TokenIgnores = (:.*:`.*`)|(<.*>)
+
+Clear files generated by local building of the documentation
+------------------------------------------------------------
+
+When you build documentation locally, the build process generates ``_autosummary`` files in one
+or more ``_autosummary`` directories. When you next run Vale locally, it
+finds these files and checks them, which likely results in it identifying lots of issues.
+
+To clear ``_autosummary`` files, clean the ``doc`` folder:
+
+#. If the Ansys Python Manager and the **Administrator** window are not
+ open, open them. For more information, see :ref:`Ansys_Python_Manager`.
+#. In the **Administrator** window, use the ``cd`` command to go to the
+ root folder.
+#. Run this Git command::
+
+ git clean -f -d -x doc
+
+#. Use the ``cd`` command to go to the ``doc`` directory.
+#. Run this Vale command to install the latest rules for the Google style guidelines locally::
+
+ vale sync
+
+#. Run this Vale command to check all RST and MD files in the ``doc`` directory::
+
+ vale .
+
+If ``_autosummary`` directories or files are still present, you have accidentally pushed them
+to the repository. You want to delete these directories or files from your local branch and
+push this change to the repository so that they are also removed from it.
+
+Specify a specific Vale version
+-------------------------------
+
+If you push your changes to a PR and Vale raises lots of inappropriate errors about titles not
+being in sentence case when they are already in title case, in the ``.github/workflows`` directory,
+open the :file:`ci_cd.yml` file and then update the "Documentation Style Check" to use Vale
+version 2.29.5::
+
+ docs-style:
+ name: Documentation Style Check
+ runs-on: ubuntu-latest
+ steps:
+ - name: PyAnsys documentation style checks
+ uses: ansys/actions/doc-style@v4
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ vale-version: "2.29.5"
diff --git a/doc/source/content-writing/examples-writers/index.rst b/doc/source/content-writing/examples-writers/index.rst
new file mode 100644
index 000000000..4cb874696
--- /dev/null
+++ b/doc/source/content-writing/examples-writers/index.rst
@@ -0,0 +1,37 @@
+.. _examples_writers:
+
+Content in examples
+===================
+
+Many PyAnsys libraries have an "Example" section. The `sphinx_gallery `_
+extension (Sphinx-Gallery) are typically used to generate standalone, downloadable Python scripts
+(PY files) or Jupyter notebooks (IPYNB files) that you can run. However, some
+PyAnsys libraries use the `nbsphinx `_ extension,
+which is specifically designed for working with and integrating Jupyter notebooks
+into your Sphinx documentation.
+
+When setting up a PyAnsys library, developers choose between Sphinx-Gallery or ``nbsphinx``
+based on their specific documentation needs and the format of their code examples.
+
+- Sphinx-Gallery is chosen if a gallery of examples is to be created from Python scripts and Jupyter
+ notebooks. This extension automatically generates thumbnail images and links to the source code
+ for each example. It also provides a number of configuration options for customizing the
+ appearance of the gallery, providing a great way to showcase how to use your library
+ in a structured manner with embedded code examples, explanations, and narrative text.
+
+- The ``nbsphinx`` extension is chosen if developers want to integrate Jupyter notebooks into their Sphinx documentation. This
+ extension processes Jupyter notebooks as inputs and offers custom Sphinx directives for rendering
+ these notebooks as interactive HTML pages or LaTeX output. Within these formats, you can execute
+ and modify code cells. Furthermore, ``nbsphinx`` can execute unevaluated notebooks automatically
+ during the Sphinx build process. While this extension allows for some customization on the
+ appearance of Jupyter notebooks in your Sphinx documentation, its scope is narrower than that
+ of Sphinx Gallery.
+
+For implementation information, see :ref:`sphinx-gallery` and :ref:`nbsphinx`.
+
+.. toctree::
+ :maxdepth: 3
+ :hidden:
+
+ sphinx-gallery
+ nbsphinx
diff --git a/doc/source/content-writing/examples-writers/nbsphinx.rst b/doc/source/content-writing/examples-writers/nbsphinx.rst
new file mode 100644
index 000000000..1f50e006f
--- /dev/null
+++ b/doc/source/content-writing/examples-writers/nbsphinx.rst
@@ -0,0 +1,66 @@
+.. _nbsphinx:
+
+Use ``nbsphinx``
+================
+
+``nbsphinx`` uses a source parser for Jupyter notebooks (IPYNB files) to generate
+interactive examples. This extension uses custom Sphinx directives to show notebook
+code cells (and their results) in both HTML and LaTeX output. If a notebook is unevaluated
+(has no stored output cells), it is automatically executed during the Sphinx documentation
+build process. Notebooks with stored output cells are not executed by default.
+
+Install Jupyter kernel
+----------------------
+
+To execute and convert Jupyter notebooks, you must have the appropriate Jupyter kernel
+installed in your development environment. For example, you can install the IPython kernel
+from the `ipykernel `_ package.
+
+Create and document notebooks
+-----------------------------
+
+When using ``nbsphinx``, you place the IPYNB files for the "Examples" section in the
+``examples`` directory. To add documentation to your notebooks, use Markdown cells.
+
+
+Configure the use of ``nbsphinx`` in the Sphinx configuration file
+-------------------------------------------------------------------
+
+To build the "Examples" section, developers configure the use of the ``nbsphinx``
+extension in the project's :file:`conf.py` file. After installing and adding this
+extension to the ``extensions`` variable as described in :ref:`add_sphinx_extensions`,
+developers configure the ``nbsphinx_execute`` and ``nbsphinx_thumbnails`` variables.
+
+Here is what these variables look like in the :file:`conf.py` file for PyAnsys Geometry:
+
+.. code-block:: rst
+
+ # Examples gallery customization
+ nbsphinx_execute = "always"
+ nbsphinx_custom_formats = {
+ ".mystnb": ["jupytext.reads", {"fmt": "mystnb"}],
+ }
+ nbsphinx_thumbnails = {
+ "examples/01_getting_started/01_math": "_static/thumbnails/101_getting_started.png",
+ "examples/01_getting_started/02_units": "_static/thumbnails/101_getting_started.png",
+ "examples/01_getting_started/03_sketching": "_static/thumbnails/101_getting_started.png",
+ "examples/01_getting_started/04_modeling": "_static/thumbnails/101_getting_started.png",
+ "examples/01_getting_started/05_plotter_picker": "_static/thumbnails/101_getting_started.png", # noqa: E501
+ "examples/02_sketching/basic_usage": "_static/thumbnails/basic_usage.png",
+ "examples/02_sketching/dynamic_sketch_plane": "_static/thumbnails/dynamic_sketch_plane.png",
+ "examples/02_sketching/advanced_sketching_gears": "_static/thumbnails/advanced_sketching_gears.png", # noqa: E501
+ "examples/03_modeling/add_design_material": "_static/thumbnails/add_design_material.png",
+ "examples/03_modeling/plate_with_hole": "_static/thumbnails/plate_with_hole.png",
+ "examples/03_modeling/tessellation_usage": "_static/thumbnails/tessellation_usage.png",
+ "examples/03_modeling/design_organization": "_static/thumbnails/design_organization.png",
+ "examples/03_modeling/boolean_operations": "_static/thumbnails/boolean_operations.png",
+ }
+ nbsphinx_epilog = """
+
+Add ``nbsphinx`` to the documentation requirements
+--------------------------------------------------
+
+To include ``nbsphinx`` in your project's documentation requirements, you must
+add it as a dependency. Depending on the project's configuration, you add the required ``pip``
+packages in either the :file:`pyproject.toml` file or the :file:`requirements_doc_txt` file.
+For more information, see :ref:`doc_ext_requirements`.
diff --git a/doc/source/content-writing/examples-writers/sphinx-gallery.rst b/doc/source/content-writing/examples-writers/sphinx-gallery.rst
new file mode 100644
index 000000000..8a86beaaf
--- /dev/null
+++ b/doc/source/content-writing/examples-writers/sphinx-gallery.rst
@@ -0,0 +1,86 @@
+.. _sphinx-gallery:
+
+Use Sphinx-Gallery
+==================
+
+The `sphinx_gallery `_ extension (Sphinx-Gallery) is
+used to generate a gallery of examples from RST (or TXT) files, Python scripts
+(PY files), and even Jupyter notebooks (IPYNB files). The RST (or TXT) files
+introduce the one or more sections of examples. The PY and IPYNB files provide
+the corresponding standalone, downloadable code. Sphinx-Gallery generates an HTML
+page for each example, as well as both Python and Jupyter notebook files, which
+users can download and execute.
+
+Set up examples
+---------------
+
+When using Sphinx-Gallery, you place the files for the ``Examples`` section in the
+``examples`` directory. An RST (or TXT) file in this directory provides the
+introductory content for the section. In most libraries, a :file:`Readme.txt` file
+is used.
+
+In a larger library, you typically organize examples in subdirectories by categories.
+An RST or TXT file in each subdirectory then provides the introductory content for the
+examples in this category.
+
+You also place the PY and IPYNB files in the ``examples`` directory or subdirectories.
+These files contain the code and documentation explaining this code.
+
+- For Python files, you must use a specific structure and reStructuredText syntax. For more
+ information, see `Structuring Python scripts for Sphinx-Gallery `_
+ in the Sphinx-Gallery documentation. For information on adding a new example in a PY
+ file, see :ref:`adding_a_new_gallery_example`. You can use this example as a template
+ for creating Python files for Sphinx-Gallery.
+
+- For IPYNB files, you use Markdown cells to provide section headings and to provide
+ context and explanations for the code in the code cells.
+
+Configure the use of Sphinx-Gallery in the Sphinx configuration file
+--------------------------------------------------------------------
+
+To build the "Examples" section, developers configure the use of Sphinx-Gallery in
+the project's Sphinx configuration (``doc/source/conf.py``) file. After installing
+and adding this extension to the ``extensions`` variable as described in
+:ref:`add_sphinx_extensions`, developers configure the ``sphinx_gallery_conf`` variable.
+This variable declares many values, including ``examples_dirs`` for the relative path to the
+``examples`` directory and ``gallery_dirs`` for the relative path where the gallery-generated
+outputs are saved.
+
+While the values declared by the ``sphinx_gallery_conf`` variable vary from project to
+project, here is what this variable looks like in the :file:`conf.py` file for PyAEDT:
+
+.. code-block:: python
+
+ sphinx_gallery_conf = {
+ # convert rst to md for IPYNBb
+ "pypandoc": True,
+ # path to your examples scripts
+ "examples_dirs": ["../../examples/"],
+ # path where to save gallery generated examples
+ "gallery_dirs": ["examples"],
+ # Pattern to search for examples files
+ "filename_pattern": r"\.py",
+ # Remove the "Download all examples" button from the top level gallery
+ "download_all_examples": False,
+ # Sort gallery examples by file name instead of number of lines (default)
+ "within_subsection_order": FileNameSortKey,
+ # directory where function granular galleries are stored
+ "backreferences_dir": None,
+ # Modules for which function level galleries are created. In
+ "doc_module": "ansys-pyaedt",
+ "image_scrapers": ("pyvista", "matplotlib"),
+ "ignore_pattern": "flycheck*",
+ "thumbnail_size": (350, 350),
+ # 'first_notebook_cell': ("%matplotlib inline\n"
+ # "from pyvista import set_plot_theme\n"
+ # "set_plot_theme('document')"),
+ }
+
+
+Add Sphinx-Gallery to the documentation requirements
+----------------------------------------------------
+
+To include Sphinx-Gallery in your project's documentation requirements, you must
+add it as a dependency. Depending on the project's configuration, you add the required ``pip``
+packages in either the :file:`pyproject.toml` file or the :file:`requirements_doc_txt` file.
+For more information, see :ref:`doc_ext_requirements`.
diff --git a/doc/source/content-writing/index.rst b/doc/source/content-writing/index.rst
new file mode 100644
index 000000000..f988c8a89
--- /dev/null
+++ b/doc/source/content-writing/index.rst
@@ -0,0 +1,46 @@
+.. _content_writing:
+
+Content writing
+===============
+
+Earlier sections of this guide are written primarily for PyAnsys developers by PyAnsys
+developers. This section is written for anyone who wants to contributing new or revise
+existing content in the documentation for a PyAnsys library. The goal is to
+provide content contributors with the information that they need to write clear, consistent,
+effective, and user-friendly content in the order in which they need to know it.
+
+Comprehensive information on content writing is organized as follows:
+
+- :ref:`content_contrib_setup`: Describes PyAnsys libraries, explains how to set up a
+ content development environment, and provides links to many resources relevant to
+ creating and maintaining PyAnsys documentation.
+
+- :ref:`rst_files_writers`: Explains how reStructuredText (RST) files define the hierarchy
+ of the documentation and provide manually authored content. This section also describes
+ how to view and reuse the formatting of any documentation page and summarizes the
+ formatting rules to follow so that your content contributions are rendered correctly.
+
+- :ref:`py_files_writers`: Explains how docstrings in Python (PY) files provide
+ descriptions for the Python objects that are used to interact with a PyAnsys library. This
+ section also explains how PY files are set up and summarizes the formatting rules
+ for docstrings, code comments, and message strings.
+
+- :ref:`examples_writers`: Explains the Sphinx extensions that PyAnsys developers are
+ using to generate the examples in the "Examples" section of their PyAnsys documentation
+ and how to format the source files so that the content in the renders correctly.
+
+- :ref:`content_how_tos`: Explains how to perform tasks associated with contributing
+ to PyAnsys documentation, including how to review and create GitHub PRs (pull requests).
+ As you become a more experienced contributor, this subsection and the :ref:`resources_writers`
+ page are likely to be the content that you refer to most often.
+
+
+.. toctree::
+ :maxdepth: 3
+ :hidden:
+
+ content-contrib-setup/index
+ rst-files-writers/index
+ py-files-writers/index
+ examples-writers/index
+ content-how-tos/index
diff --git a/doc/source/content-writing/py-files-writers/code-comments-message-strings.rst b/doc/source/content-writing/py-files-writers/code-comments-message-strings.rst
new file mode 100644
index 000000000..c58a7ed84
--- /dev/null
+++ b/doc/source/content-writing/py-files-writers/code-comments-message-strings.rst
@@ -0,0 +1,67 @@
+.. _py_code_comments_message_strings:
+
+Code comments and message strings
+=================================
+
+Python files often contain code comments and message strings.
+
+- Code comments provide information to make the code more readable and maintainable.
+- Message strings display information to users. Developers can also use message
+ strings for debugging purposes to better understand the flow of the code.
+
+.. _py_code_comments:
+
+Code comments
+-------------
+
+Developers know that adding comments to code is a good practice when logic
+might be hard to understand at first glance. They also know to avoid over-commenting
+or writing comments that explain the obvious.
+
+A code comment starts with the hash character (``#``) and a single space. It extends to
+the end of the physical line. At least two spaces should separate the code from the comment.
+
+While the code comments in PY files are not visible to users of the library. they are visible
+to contributors of the library. Thus, when reviewing PY files, make suggestions for correcting
+misspelled words and bad grammar.
+
+You can also make suggestions for formatting code comments consistently. For example, you
+might suggest starting all code comments in a PY file with a simple verb that always begins
+with an uppercase letter. You might also suggest always concluding all code comments within
+a code block with a period (``.``). Or, you might suggest that only code comments containing
+multiple sentences should conclude with a period. Your objective is to ensure that code comments
+within a code block are well written and consistently formatted.
+
+.. _py_message_strings:
+
+Message strings
+---------------
+
+Developers can create a simple message by assigning to a variable a text string that
+is enclosed in either two single (``''``) or two double (``""``) quotation marks. They can
+create a multi-line message using triple (``"""``) quotation marks like those used
+for docstrings. Additionally, developers can perform other operations on strings,
+such as concatenation, interpolation, slicing, and formatting.
+
+Whenever possible, use double quotation marks to surround a message string.
+If you need to use quotation marks inside the message string, then use single quotation marks.
+The only exception is if you need to use double quotations inside the message string to
+specify possible options that are string values. In this case, use single quotation
+marks to surround this line and double quotation marks for other options::
+
+ message=(
+ "Conductor type is invalid. " \
+ 'Options are "SIGNAL", "POWER", and "SUBSTRATE".'
+ )
+
+When reviewing PY files, you want to ensure that message strings are clear
+and concise so that users can easily understand the information or instructions
+that they provide.
+
+You should always ensure that a message string is a complete sentence
+with a concluding period. Message strings should not conclude with an exclamation
+point (``!``) or use the word *please*.
+
+Because tests written for a PyAnsys project might check that a particular message
+is shown, making changes to a message string could necessitate you having to also update
+any test that checks for it. For more information, see :ref:`resolve_mismatched_message_strings`.
diff --git a/doc/source/content-writing/py-files-writers/docstring-format-rules.rst b/doc/source/content-writing/py-files-writers/docstring-format-rules.rst
new file mode 100644
index 000000000..1f956ba53
--- /dev/null
+++ b/doc/source/content-writing/py-files-writers/docstring-format-rules.rst
@@ -0,0 +1,575 @@
+.. _docstring_formatting_rules:
+
+Docstring formatting rules
+==========================
+
+In the PY files for PyAnsys libraries, docstrings always start and
+end with triple quotation marks (``"""``). Within a docstring, content is
+formatted similarly to RST files.
+
+The first docstring in a PY file provides a short summary of the module
+itself. For short summaries to fit on one line in the library's API reference
+summary tables, you must keep the line lengths of your docstrings
+to no more than 100 characters. This is different than the maximum line length
+for source code, which might be set to as many as 120 characters.
+
+
+Most of the time, a module contains only a single class. This page summarizes
+PyAnsys-specific formatting rules for the sections more commonly found in a
+docstring for a class or one of its methods:
+
+- Short summary
+- Deprecation warning
+- Extended summary
+- Parameters
+- Returns
+- Raises
+- Examples
+
+In most PyAnsys libraries, the docstrings in PY files do not contain these sections:
+
+- Yields
+- Receives
+- Other Parameters
+- Warns
+- Warnings
+- See Also
+- Notes
+- References
+
+If a docstring in a PY file contains one of these sections,
+see `Sections `_ in the *numpydoc Style guide*
+for information on how to format its content. This page also indicates the order
+of all sections possible in a docstring.
+
+Docstring sections are always contained within the triple quotation marks that denote
+a docstring. The sections more commonly found in PyAnsys docstrings must be in
+the order indicated in this page's right pane.
+
+Some of the docstrings shown on this page display ellipses to indicate
+that they provide additional sections.
+
+
+.. tip::
+ You might want to open one of the larger PY files for your PyAnsys library
+ and look at its docstrings while reading about how they are formatted. These
+ PY files are typically in the ``src`` directory.
+
+
+Short summary
+-------------
+
+This unnamed docstring section is a one-line summary written in plain English. This
+single line immediately follows the declaration of a function, class, or method to
+briefly describe what it does. A short summary for these Python objects is mandatory.
+If it is not present, documentation style tools in the CI/CD process raise errors
+when you push changes to a PR.
+
+You can declare the short summary on the same line as the opening quotation marks
+of the docstring or on the next line. While `PEP 257 `_ accepts both ways,
+docstrings must be consistent across your project. If the developers of a PyAnsys
+library are declaring the short summary on the same line as the opening quotation marks,
+they have turned off ``"GL01"`` checking in the ``numpydoc_validation_checks`` dictionary
+of the ``numpydoc`` extension. For more information on documentation style tools and the
+validation of NumPy-style docstrings, see `doc_style_tools_>`.
+
+The short summary should not use code entities to refer to the names of Python
+objects unless absolutely necessary. This is because the use of code entities
+reduces readability of the short summary.
+
+Because the short summary cannot exceed the maximum line length of 100 characters,
+use a sentence fragment that starts with a verb and ends with a period. If additional
+information is needed to clarify what the function, class, or method does, provide
+this information in the :ref:`docstring_extended_summary`.
+
+.. note::
+ In Python, functions are not defined within a class but rather perform actions or
+ operations on collections (lists, tuples, dictionaries, and sets). Methods, which
+ are functions defined within a class, are associated with instances of that class.
+ They perform actions or operations related to that class. While the subsequent content
+ focuses on docstrings for classes and methods, docstrings for functions are
+ basically formatted the same as those for methods.
+
+Short summary for a class
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A class is a *noun* representing a collection of methods. For consistency within PyAnsys libraries,
+start the short summary for a class with a verb ending in "s" or "es" so that the summary table
+of the classes in a module have consistently formatted descriptions::
+
+ class Emit(Design, object):
+ """Provides the EMIT application interface.
+
+ ...
+
+ """
+
+Initializing an instance of a class often requires specifying parameters, which are indicated
+in a ``def __init__`` definition. These parameters are described in the :ref:`docstring_parameters`
+section of the docstring for the class.
+
+Short summary for a method
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A method is a *verb* representing an action that can be performed. For consistency
+within PyAnsys libraries, start the short summary for a method with a verb not ending
+in "s" or "es" so that the summary table of the methods for a class have consistently
+formatted descriptions::
+
+ def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None):
+ """Export mesh statistics to a file.
+
+ ...
+
+ """
+
+Using a method almost always requires specifying parameters, which are indicated in parentheses
+in the method's definition. These parameters, except for the ``self`` parameter, are always described
+in the :ref:`docstring_parameters` section for the method. The ``self`` parameter does not have to
+be documented because it is a reference to the instance of the parent class (and its properties)
+that the method is being called on.
+
+Methods with a leading underscore (``_``) are *protected* methods, meaning that they are not
+rendered in the documentation unless an explicit request is made to add them using Sphinx
+directives. The plus side to this is that docstrings for protected methods can be more
+developer-focused. However, writing clear docstrings for protected methods is still
+important.
+
+If a method has an ``@exceperty`` decorator, it means that it has no parameters. Thus,
+you can remove the "Parameters" section from the docstring for this method.
+
+If a method has an ``@property`` decorator, it is turned into a property, which must be described
+as a noun rather than a verb. Because the resulting property cannot have parameters, it does
+not have a "Parameters" section. If a ``setter`` follows the ``@property`` decorator, do not
+add a docstring for the setter. A ``setter`` simply exposes both the GET and SET methods rather
+than only the GET method. Developers should include examples to show how to use the GET and SET
+methods if necessary. A "Returns" section is only included if the property calculates
+and returns a result. Otherwise, the description should clearly explain the value that
+is returned.
+
+Deprecation warning
+-------------------
+
+This unnamed docstring section follows the short summary only if the Python object is being
+deprecated or has been deprecated. It consists of a ``deprecated`` directive that warns
+users about when this object is to be removed (or was removed) from the API. The
+``deprecated`` directive gives a reason for the deprecation, such as the
+object is superseded or duplicates functionality found elsewhere. Lastly, it recommends
+how to obtain the same functionality.
+
+Here is an example of a PyAEDT method with a ``deprecated`` directive. It indicates
+the version for the deprecation and explains that this method is superseded by functionality
+in another method. It uses the ``func`` role to link to the method that should be used::
+
+ def create_polygon_from_points(self, point_list, layer_name, net_name=""):
+ """Create a new polygon from a point list.
+
+ .. deprecated:: 0.6.73
+ Use the :func:`create_polygon` method instead. It now supports point lists as arguments.
+
+.. _docstring_extended_summary:
+
+Extended summary
+----------------
+
+If the short summary does not clearly and fully explain the functionality of the object,
+this unnamed docstring section provides the additional information that is needed in
+complete sentences. A blank line must always be inserted before and after the extended
+summary.
+
+While you can use inline code entities in the extended summary, you should not describe
+any named objects that are parameters here in this section because they are described in
+the subsequent "Parameters" section. You should place any needed implementation information
+or background theory in a "Notes" section. For more information, see
+`Sections `_ in the *numpydoc Style guide*.
+
+.. _docstring_parameters:
+
+Parameters
+----------
+
+This named docstring section describes the parameters listed in the definition
+of an instance method. The first parameter in the definition is ``self`` by convention.
+As explained earlier, it represents the instance of the class that a method is being
+called on. The other parameters listed in the definition pass input data. In the "Parameters"
+section, all parameters except for ``self`` must be documented in the order in which they appear
+in the definition.
+
+Parameters for initializing an instance of a class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can find the parameters for initializing a class in an ``__init__`` definition.
+
+Here is the ``__init__`` definition for the PyAEDT ``Emit`` class::
+
+ def __init__(
+ self,
+ projectname=None,
+ designname=None,
+ solution_type=None,
+ setup_name=None,
+ specified_version=None,
+ non_graphical=False,
+ new_desktop_session=True,
+ close_on_exit=True,
+ student_version=False,
+ machine="",
+ port=0,
+ aedt_process_id=None,
+ ):
+
+.. _docstring_parameters_optional_usage:
+
+The parameters for this class are defined in the "Parameters" section like this:
+
+.. code-block:: rst
+
+ Parameters
+ ----------
+ projectname : str, optional
+ Name of the project to select or the full path to the project
+ or AEDTZ archive to open. The default is ``None``, in which case
+ an attempt is made to get an active project. If no projects are
+ present, an empty project is created.
+ designname : str, optional
+ Name of the design to select. The default is ``None``, in which case
+ an attempt is made to get an active design. If no designs are
+ present, an empty design is created.
+ solution_type : str, optional
+ Solution type to apply to the design. The default is ``None``, in which
+ case the default type is applied.
+ setup_name : str, optional
+ Name of the setup to use as the nominal. The default is ``None``, in
+ which case the active setup is used or nothing is used.
+ specified_version : str, optional
+ Version of AEDT to use. The default is ``None``, in which case
+ the active setup is used or the latest installed version is
+ used.
+ non_graphical : bool, optional
+ Whether to launch AEDT in non-graphical mode. The default
+ is ``False``, in which case AEDT is launched in graphical mode.
+ This parameter is ignored when a script is launched within AEDT.
+ new_desktop_session : bool, optional
+ Whether to launch an instance of AEDT in a new thread, even if
+ another instance of the ``specified_version`` is active on the
+ machine. The default is ``True``.
+ close_on_exit : bool, optional
+ Whether to release AEDT on exit. The default is ``False``.
+ student_version : bool, optional
+ Whether to start the AEDT student version. The default is ``False``.
+ machine : str, optional
+ Machine name to connect the desktop session to. The default is ``""``.
+ This parameter works only in AEDT 2022 R2 or later. The remote server
+ must be up and running with the ``ansysedt.exe -grpcsrv portnum``
+ command. If the machine is ``"localhost"``, the server also starts
+ if it is not present.
+ port : int, optional
+ Port number for starting the desktop communication on an already
+ existing server. The default is ``0``. This parameter is ignored when
+ creating a server and works only in AEDT 2022 R2 or later. The
+ remote server must be up and running with the ``ansysedt.exe -grpcsrv portnum``
+ command.
+ aedt_process_id : int, optional
+ Process ID for the instance of AEDT to point PyAEDT at. The default is
+ ``None``. This parameter is only used when ``new_desktop_session = False``.
+
+Parameters for a function or method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. vale off
+
+You can find the parameters for a function or method in parentheses in its definition
+(function signature). Here is the definition for the ``add_sweep`` method in the PyAEDT
+:file:`SolveSetup.py` file::
+
+ @pyaedt_function_handler()
+ def add_sweep(self, sweepname=None, sweeptype="Interpolating"):
+
+.. vale on
+
+The parameters for this method are defined in the "Parameters" section like this:
+
+.. code-block:: rst
+
+ Parameters
+ ----------
+ sweepname : str, optional
+ Name of the sweep. The default is ``None``.
+ sweeptype : str, optional
+ Type of the sweep. The default is ``"Interpolating"``.
+
+
+For the first parameter, the behavior that occurs when the default of ``None`` is used
+is unclear. For the second parameter, no options other than the default are given.
+Because the goal is to have well written and consistently formatted docstrings, when
+submitting suggested changes in a PR, you would want to add comments like these to the
+parameter descriptions:
+
+- For the ``sweepname`` parameter, what behavior occurs when the default of
+ ``None`` is used?
+- For the ``sweeptype`` parameter, what are all the options so that they
+ can be listed in the description alphabetically in either a sentence or itemized list?
+
+For information on making a comment when reviewing a PR, see :ref:`add_comment_on_line`.
+
+Parameter formatting
+~~~~~~~~~~~~~~~~~~~~
+
+The first line for each parameter provides the name and data type and indicates
+if specifying a value is optional. Always follow the parameter name with a space,
+a colon, and a space. Next, specify the data type of the parameter, being as precise
+as possible.
+
+Parameter data types
+^^^^^^^^^^^^^^^^^^^^
+
+The preceding examples show the ``str``, ``bool``, ``int``, and ``list`` data types.
+Additional common data types include ``float``, ``dict``, and ``tuple``. For more
+information, see :ref:`py_file_primitive_data_types` and :ref:`py_file_collections`.
+Because your PyAnsys project might support other data types, consult with your developers
+before making any changes to them.
+
+Here are some guidelines to follow when specifying the one or more data types that a parameter
+supports as inputs:
+
+- For a parameter with a numerical default, let the developer set the data type. While
+ it seems intuitive that a numerical default with a decimal point is a float, a float value
+ might accept an integer (and vice versa).
+
+- When the code shows that a parameter is being converted to a string with ``str(rjc)``, the
+ data type can be a string, float, or integer. You can format these multiple data types as
+ indicated in the next bullet.
+
+- When a parameter supports multiple data types, place the word "or" between each type::
+
+ isconvergence : bool or str or list
+
+Optional parameters
+^^^^^^^^^^^^^^^^^^^
+
+A parameter is optional if a default is shown in the definition. If no value is programmatically
+specified for the parameter, the default is used. PyAnsys libraries use two different methods
+for providing the default for an optional parameter.
+
+In the PY files for most projects, the data type is followed by a comma and ``optional``, which is
+the method used in the two "Parameters" sections shown earlier. Following the short summary of the
+parameter, a complete sentence then provides the default.
+
+However, recent extension enhancements support placing the default after the data type, which
+eliminates the need for a sentence indicating what the default is (unless the behavior that occurs
+when this default is used is unclear). Here is a "Parameters" section that uses this second method:
+
+ .. code-block:: rst
+
+ Parameters
+ ----------
+ port : int, default: -1
+ Port to use for communication.
+ open_new_instance : bool, default: True
+ Whether to open a new instance. When ``False``, try to connect to an existing instance
+ using the URL specified by the ``url`` parameter.
+ enable_exceptions : bool, default: True
+ Whether to show Motor-CAD communication errors as Python exceptions.
+ enable_success_variable : bool, default: False
+ Whether Motor-CAD methods return a success variable (first object in tuple).
+ reuse_parallel_instances : bool, default: False
+ Whether to reuse MotorCAD instances when running in parallel. When ``True``,
+ you must free instances after use.
+ url: str, default: ""
+ Full URL for the Motor-CAD connection if connecting to an existing Motor-CAD
+ instance.
+
+Projects using the older ``optional`` method might eventually want to migrate to this newer
+method to reduce the length of many of their parameter descriptions.
+
+Parameter descriptions
+^^^^^^^^^^^^^^^^^^^^^^
+
+When writing the description for a parameter, always follow these rules, referring
+back to them as needed:
+
+- Indent the parameter's short summary and all subsequent sentences four spaces.
+
+- For the short summary, use a sentence fragment that omits a leading article
+ (such as "A," "An," or "The") and conclude this fragment with a period. Although omitting the
+ article contradicts the `Articles `_ guideline in the Google style
+ guide, removing them at the beginning of short summaries here and in other docstring sections
+ ensures that the first word is an important descriptor.
+
+- End the short summary (and complete sentences) with prepositions if it improves readability.
+ For example, "Frequency to set the adaptive convergence at" is more readable than
+ "Frequency at which to set the adaptive convergence."
+
+- After the short summary, use complete sentences, including articles, to provide additional
+ information.
+
+- When a sentence is used to specify the default, this sentence should immediately follow the
+ short summary. If other possible options are not evident, begin the next sentence with an
+ "Options are" phrase and then specify all options, including the default, in alphabetical
+ order. If there are many options, consider formatting the options in a bulleted list. Or,
+ in situations where listing specific options is not practical or necessary, format the
+ parameter description similarly to this one::
+
+ unit : str, optional
+ Unit of the frequency. For example, ``"GHz"`` or ``"MHz"``. The default is ``"GHz"``.
+
+- When specifying the default for a string parameter, surround the default in both
+ double backticks (:code:`\`\``) and double quotation marks (``"``)::
+
+ The default is ``"0.5cm"``.
+
+- When the default for a string parameter is ``None``, surround the default only in
+ double backticks because ``None`` has programmatic meaning and is not a string value.
+ ``None`` represents the absence of a value or a null value. Thus, the sentence
+ indicating this default usually requires a non-restrictive "in which case" clause that
+ explains the behavior that occurs when ``None`` is used. Many examples of using an
+ "in which case`` clause appear in the "Parameters" section shown earlier for
+ the PyAEDT ``Emit`` class.
+
+- Start the description for a Boolean parameter with a "Whether to" phrase and surround
+ the default in only double backticks because ``True`` and ``False`` have programmatic
+ meaning and are not string values::
+
+ include_signal : bool, optional
+ Whether to generate extended signal nets. The default is ``True``.
+
+ Do not include "or not" in the description because the true or false nature of a Boolean
+ parameter makes this obvious. If the default for the Boolean parameter does not clearly
+ describe the behavior that occurs, follow the default with a non-restrictive "in which case"
+ clause that explains the behavior::
+
+ non_graphical : bool, optional
+ Whether to launch AEDT in non-graphical mode. The default is ``False``,
+ in which case AEDT is launched in graphical mode. This parameter is
+ ignored when a script is launched within AEDT.
+
+- Enclose all code entities in double backticks. If you surround a code entity in only a single
+ backtick (:code:`\``), it is incorrectly rendered in italics in the documentation.
+
+- Use the present tense for verbs. Occurrences of "will" cause `Vale `_ to
+ raise warnings about not using phrases expressing future actions.
+
+- When documenting variable length positional or keyword arguments, leave the leading single
+ asterisk (``*``) or double asterisks (``**``) in front of their names::
+
+ *args : tuple
+ Additional arguments to pass as keyword arguments.
+ **kwargs : dict, optional
+ Extra arguments to the ``metric`` parameter. For a list of all possible arguments,
+ see the ``metric`` documentation.
+
+Returns
+-------
+
+The docstring for a class should not have a named "Returns" section because it is assumed that
+a class always returns an instance of itself. If a class has a "Returns`` section, you can
+remove it from the docstring.
+
+In Python, a method decorator is a function that can be used to modify or extend the behavior of
+a method in a class without changing the method's source code. Method decorators are typically
+applied to methods using the ``@`` symbol followed by the decorator function's name. They are
+usually defined separately from the class and are often used to wrap or modify the method that
+they decorate.
+
+When a function or method has no decorator, the vanilla implementation of a Python method is
+being used, which means that the function or method has no return value. (While there is actually
+a return value of ``None``, this is something that you do not document.) For such methods, you
+can remove the "Returns" section from their docstrings.
+
+When a function returns one or more values, the "Returns" section must provide the
+data type and a description for each value returned.
+
+When only a non-Boolean value is returned, format the "Returns" like this:
+
+.. code-block:: rst
+
+ Returns
+ -------
+ int
+ Port being used for communication.
+
+
+When only a Boolean value is returned, format the "Returns" section like this:
+
+.. code-block:: rst
+
+ Returns
+ -------
+ bool
+ ``True`` when successful, ``False`` when failed.
+
+When a method has an ``@exceperty`` decorator, it always returns a Boolean value. Thus,
+format the ``Returns`` section for such a method as shown in the preceding example.
+
+When multiple values are returned, format the "Returns" section like the "Parameters"
+section:
+
+.. code-block:: rst
+
+ Returns
+ -------
+ err_code : int
+ Non-zero value that indicates an error code or ``0`` on success.
+ err_msg : str or None
+ Human-readable error message, or ``None`` on success.
+
+Raises
+------
+
+This named docstring section is optional. It lists the errors that can be raised and explains when
+they are raised. While many PyAnsys libraries do not include a "Raises" section in their docstrings,
+including this section can be valuable for users.
+
+.. code-block:: rst
+
+ Raises
+ ------
+ RuntimeError
+ If the name given is not the name of an existing result set and a current result
+ set already exists.
+
+Examples
+--------
+
+This named section is optional but strongly recommended. The one or more interactive examples placed
+in this section demonstrate usage. They do not provide a testing framework. Those types of tests
+are typically placed in the ``tests`` directory. For more information, see :ref:`testing`.
+
+According to documentation published by the Python organization, the `doctest `_ module executes
+the examples in the "Examples" section of the docstring to verify that they work.
+
+Place any description of what the example code demonstrates immediately after the ``Examples`` section
+heading. Follow this description with a blank line. Then, precede each line of code with three right
+carats (``>>>``) to render them in a code block.
+
+Use blank lines to separate comments from lines of code. Also use blank lines
+to separate multiple code examples.
+
+Here is an "Examples" section for the ``element_dot`` method in PyDPF-Core:
+
+.. code-block::
+
+ Examples
+ --------
+ Compute the element-wise dot product.
+
+ >>> from ansys.dpf import core as dpf
+ >>> import numpy as np
+ >>> data = np.random.random((10, 3))
+ >>> field_a = dpf.field_from_array(data)
+ >>> field_b = dpf.field_from_array(data)
+ >>> fout = dpf.help.element_dot(field_a, field_b)
+ >>> fout.shape
+ 10
+
+ >>> # Numpy equivalent
+ >>> arr_a = np.random.random((10, 3))
+ >>> arr_b = np.random.random((10, 3))
+ >>> edot = np.sum(arr_a*arr_b, 1)
+ >>> edot.shape
+ (10,)
+
+The returned value for this example is ``10``. If you are writing an example and want to test
+it locally, you can copy and paste the lines beginning with the three right carats into
+JupyterLab and execute them. You can then paste the returned value into the example but
+without the three right carats.
diff --git a/doc/source/content-writing/py-files-writers/index.rst b/doc/source/content-writing/py-files-writers/index.rst
new file mode 100644
index 000000000..2ef780944
--- /dev/null
+++ b/doc/source/content-writing/py-files-writers/index.rst
@@ -0,0 +1,89 @@
+.. _py_files_writers:
+
+Content in PY files
+###################
+
+In Python, a module is a PY file that contains Python objects such
+as interfaces, functions, classes, methods, parameters, attributes,
+enums (enumerations), properties, and constants. These objects each
+have a docstring that describes and explains how to use it to interact
+with the library. When building documentation, `Sphinx `_ assembles
+the content in these docstrings to generate API reference documentation.
+
+This section covers the setup and processing of PY files by Sphinx,
+fundamental Python objects, and formatting rules for docstrings, code comments,
+and message strings.
+
+For resources related to PY files, see :ref:`style_format_resources`.
+To learn how PY files for PyAnsys libraries are formatted, see :ref:`py_file_format`.
+
+PY file setup
+-------------
+
+A Python client library consists of PY files that are organized and
+packaged in a way that makes it easy for users to interact with the library
+and its underlying APIs and services.
+
+In a PyAnsys client library, PY files are usually organized in the
+``src\ansys`` directory. However, there are exceptions. For example, in PyAEDT,
+the Python files are organized in the ``pyaedt`` directory.
+
+Each subpackage contains an :file:`__init__.py` file, which contains any
+necessary package-level initialization code.
+
+NumPy docstrings
+-----------------
+
+Properly documented code is crucial to code readability, maintainability, and
+usability. For information on the two most popular conventions for formatting
+docstrings, see the `numpydoc style guide `_ and
+`Comments and Docstrings `_ in the *Google Python Style Guide*.
+
+While Sphinx supports both the ``numpydoc`` extension for NumPy-style docstrings
+and the ``napoleon`` extension for Goggle Python-style docstrings, PyAnsys libraries
+use NumPy-style docstrings because this convention is favored by the most well known
+Python scientific packages.
+
+For information on how to format docstrings so that they render correctly in PyAnsys
+API reference documentation, see :ref:`py_file_format`.
+
+API documentation extensions
+----------------------------
+
+Older PyAnsys libraries use the native (built-in) ``sphinx.ext.autodoc`` extension to
+generate API reference documentation. This extension requires developers to manually author
+RST files and import code, which means that they can overlook Python objects when
+setting up their API reference documentation. For more information, see
+`sphinx.ext.autodoc `_ in the Sphinx documentation.
+
+Newer PyAnsys projects use the external `Sphinx AutoAPI `_
+extension to generate API reference documentation. This extension finds and generates content
+by parsing the source code, ensuring that the API reference documentation includes
+every Python client object in every PY file. Generally, API members in projects using
+Sphinx Auto API are ordered as follows:
+
+- Subpackages
+- Submodules
+- Exceptions
+- Classes
+- Functions
+- Methods
+
+The PyAnsys core team has contributed to the Sphinx AutoAPI extension to make the API
+reference documentation that it generates much more navigable and attractive. The goal
+is to eventually transition all PyAnsys libraries to use Sphinx AutoAPI so that all API
+reference documentation looks like this sample page from the PyAnsys Geometry documentation:
+
+.. image:: ..//_static/AutoAPI-output-modified.png
+ :alt: API reference documentation
+
+For more information on adding Sphinx extensions to a project, see :ref:`add_sphinx_extensions`.
+
+
+.. toctree::
+ :maxdepth: 3
+ :hidden:
+
+ py-formatting
+ docstring-format-rules
+ code-comments-message-strings
diff --git a/doc/source/content-writing/py-files-writers/py-formatting.rst b/doc/source/content-writing/py-files-writers/py-formatting.rst
new file mode 100644
index 000000000..e9ac94dc3
--- /dev/null
+++ b/doc/source/content-writing/py-files-writers/py-formatting.rst
@@ -0,0 +1,157 @@
+.. _py_file_format:
+
+PY file formatting
+==================
+
+Python's flexibility and object-oriented nature allows developers to create
+and work with a wide range of custom objects and data structures.
+
+Hierarchical order of Python objects
+------------------------------------
+
+The next several topics describe the fundamental objects in Python,
+starting with the most primitive data types and ending with more complex abstractions.
+For explanations of important terms, see the `Python Glossary `_
+in the official documentation published by the Python organization.
+
+.. _py_file_primitive_data_types:
+
+Primitive data types
+~~~~~~~~~~~~~~~~~~~~
+
+The primitive, or built-in, data types provided by Python represent simple values
+that can be used to perform various operations and transformations to solve a wide
+range of problems:
+
+- **Integer**: Represents whole numbers, both positive and negative, that are used
+ for simple arithmetic operations and counting. For example, ``5``, ``-3``, ``0``,
+ and ``1000``. When defining this data type, ``int`` is used.
+- **Float**: Represents numbers with decimal points that are used for calculations
+ involving non-integer values. For example, ``3.14``, ``-0.5``, ``2.0``, and
+ ``1.0e-5`` (scientific notation). When defining this data type, ``float`` is used.
+ In PyAnsys libraries, parameters that specify angle, amplitude, capacitance,
+ impedance, resistance, and voltage have ``float`` as their data types.
+- **String**: Represents a sequence of characters, such as text, that are used for
+ text processing, manipulations, and representation. For example, ``"Hello, World!"``,
+ ``"Python"``, and ``"123"``. When defining this data type, ``str`` is used.
+- **Boolean**: Represents binary values that are used to make logical decisions and
+ control program flow. For example, ``True`` and ``False``. When defining this type
+ of data, ``bool`` is used.
+
+.. _py_file_collections:
+
+Collections
+~~~~~~~~~~~
+
+Collections are data structures used in Python to group multiple values into a single
+container so that the data can be organized and manipulated:
+
+- **List**: An ordered collection of items separated by commas and enclosed in square
+ brackets ``[]``. Lists can contain elements of different data types, including integers,
+ floats, strings, and other objects. For example, ``[1, 2, 3, "apple", "banana"]``. Lists
+ are mutable, meaning you can change their content (add, remove, or modify elements).
+ When defining this data type, ``list`` is used.
+- **Tuple**: An ordered collection of items separated by commas and enclosed in parentheses ``()``.
+ For example, ``(1, "apple", 3.14)``. Tuples can contain elements of different data types,
+ similar to lists. Tuples are immutable, meaning their content cannot be changed once created.
+ When defining this data type, ``tuple`` is used.
+- **Dictionary**: A collection of key-value pairs enclosed in curly braces ``{}``. For example,
+ ``{"name": "John", "age": 30, "city": "New York"}``. Each key is associated with a value,
+ creating a mapping between keys and their corresponding values. Dictionaries are unordered,
+ meaning they don't guarantee the order of elements. When defining this data type, ``dict`` is used.
+- **Set**: An unordered collection of unique elements enclosed in curly braces ``{}``. For example,
+ ``{1, 2, 3, 4}``. Sets are useful for eliminating duplicate values from a list and performing set
+ operations like union, intersection, and difference. When defining this data type, ``set`` is used.
+
+In summary, both lists and tuples are used for ordered sequences, dictionaries for key-value mappings,
+and sets for managing unique elements.
+
+Also, collections can be nested within one another, creating more complex data structures.
+
+Functions
+~~~~~~~~~
+
+Functions are at the same level in the Python object hierarchy as collections. Functions
+are used to operate on collections.
+
+Custom objects
+~~~~~~~~~~~~~~
+Developers define custom objects to create their own data structures and behaviors.
+This allows them to model real-world entities, concepts, or abstract data types in
+their programs, encapsulate data and behavior into reusable units, and create instances
+of these custom objects to work with.
+
+- **Class**: A blueprint or template for creating objects (instances). A class defines
+ the structure and behavior of objects of that class. Encapsulating data and behavior
+ into a single unit hides implementation details and makes managing and maintaining
+ code easier. A class typically includes attributes (variables) to store data and methods
+ (functions) to perform actions or operations related to the class. Classes are defined
+ using the ``class`` keyword, followed by the class name. A class often includes an ``__init__``
+ method to initialize object attributes.
+- **Instance**: An individual object created from a class. An instance represents
+ a specific occurrence or realization of the class's blueprint. Instances have their own
+ unique data attributes and can perform actions using the methods defined in their class.
+ You can create multiple instances of the same class, each with its own state and behavior.
+- **Method**: A function defined within a class that is associated with instances of that class.
+ Methods encapsulate behavior related to the class and can access and manipulate the
+ object's attributes. Methods can be called on instances to perform specific operations or
+ computations.
+- **Attribute**: A variable defined within a class that is used to store data associated with
+ instances of the class. Attributes can represent characteristics or properties of objects
+ created from the class. They can be accessed and modified through instances or methods.
+- **Enum**: A custom object (data type) that defines a fixed set of named, constant values that
+ are meaningful and need to be represented symbolically. Enums (enumerations) are created by
+ subclassing the ``enum`` module in Python and defining class attributes as the enum members,
+ thereby providing a structured way to work with a set of symbolic names. Enums help improve
+ code readability and maintainability by providing descriptive names for values, making the
+ code more self-explanatory.
+
+Modules
+~~~~~~~
+
+Modules are the PY files containing the Python code. They can include any of the preceding
+objects. Modules, which use the UTF-8 encoding standard by default, organize the code into
+reusable units that can be imported into other Python scripts. For example, this line of
+code imports the PyAEDT :file:`layout.py` file::
+
+ from pyaedt.edb_core import layout
+
+The :file:`layout.py` file contains two classes, ``EdbLayout`` and ``Shape``. The ``EdbLayout``
+class manages EDB methods for primitives accessible from the ``Edb.modeler`` property. The
+``Shape`` class manages EDB methods for shapes. When you import this PY file into a Python
+script, you can use all methods in these classes plus any functions defined in the file.
+
+In a PY file, you should separate methods with one blank line and separate functions with two blank
+lines. Think of this as keeping the members of a class together versus separating functions,
+which are isolated.
+
+Exceptions
+~~~~~~~~~~
+
+Exceptions can be raised during program execution to handle the error scenarios that can occur
+when working with any of the preceding objects. Exceptions can be caught and handled to prevent
+program crashes.
+
+Docstrings
+----------
+
+When developers create Python objects, they write docstrings, which are enclosed in triple
+quotation marks (``"""``), to describe these objects and explain how to use them programmatically.
+
+For an overview of how PyAnsys libraries use NumPy-style docstrings, see :ref:`numpy_docstrings`.
+This page links to descriptions for required docstring sections and provides general
+information on how to format the content in each section. For comprehensive
+information on NumPy-style docstrings and sections, see the `numpydoc Style guide `_.
+
+Because the docstrings for Python objects are read exponentially more by users than by
+the developers who draft them, docstrings should be reviewed carefully, with suggestions in
+PRs suggesting how to improve and consistently format them across this and other PyAnsys libraries.
+By using the same docstring conventions and consistent docstring formatting, PyAnsys users
+can quickly locate and fully understand how to use PyAnsys libraries.
+
+.. tip::
+ Because Python docstrings are written in reStructuredText syntax, they can
+ contain lists, notices, links, italic and bold formatting, inline code entities,
+ code blocks, and more, just like RST files.
+
+For a summary of PyAnsys-specific docstring formatting rules, see :ref:`docstring_formatting_rules`.
diff --git a/doc/source/content-writing/rst-files-writers/cards.rst b/doc/source/content-writing/rst-files-writers/cards.rst
new file mode 100644
index 000000000..c7ad23146
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/cards.rst
@@ -0,0 +1,38 @@
+.. _cards:
+
+Cards
+=====
+
+Cards are special content blocks or components that visually stand out from
+regular text. You use cards to emphasize or showcase specific pieces of
+information. While :ref:`notices ` are simple cards that you use
+admonition directives to create, you can manually create more sophisticated
+custom cards.
+
+.. note::
+ To use custom cards in your PyAnsys documentation, you must install
+ and configure the `sphinx-design `_
+ extension. For more information, see :ref:`add_sphinx_extensions`.
+
+ To see and use the cards that are shown only as images on this page,
+ click the links to their respective documentation pages. To see how these
+ cards are formatted, click the **Show Source** link in the documentation page's
+ right pane. As described in :ref:`rst_file_formatting`, you can copy content
+ from the TXT version of this file and then paste it directly into one of your
+ RST files for reuse, modifying it as needed.
+
+Here is an image of the cards on the documentation landing page for this guide.
+These cards describe and link to various sections of this guide.
+
+.. image:: ..//_static/card-dev-guide-home-page.png
+ :alt: Cards on the home page of the *PyAnsys developer's guide*
+
+Here is an image of cards on the `Docker containers `_
+page in the PyAnsys Geometry documentation. These cards link to instructions for building
+either a Windows Docker container or a Linux Docker container for the Ansys Geometry service.
+You only need to click the card for your operating system. This page and the other pages
+in the PyAnsys Geometry **Getting Started** section also have a **Go to Getting started**
+button for returning to this section's first page.
+
+.. image:: ..//_static/card-docker-containers-pyansys-geometry.png
+ :alt: Cards on the Docker containers page in the PyAnsys Geometry documentation
diff --git a/doc/source/content-writing/rst-files-writers/code-blocks.rst b/doc/source/content-writing/rst-files-writers/code-blocks.rst
new file mode 100644
index 000000000..e779177e9
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/code-blocks.rst
@@ -0,0 +1,196 @@
+.. _code_blocks:
+
+Code blocks
+===========
+
+You can introduce a short standalone code block in an RST file by ending a sentence with two
+colons (``::``). Here is an example of how to to use this method to create a standalone
+code block::
+
+ This is a normal text paragraph in your RST file. The next paragraph is a code sample::
+
+ A code sample is not processed in any way. In the documentation,
+ it is rendered in a monsopaced font in a gray block.
+
+ A code sample can span multiple lines.
+
+ This is a normal text paragraph again.
+
+In most cases, to create standalone code blocks that contain multiple lines of code,
+you should use either the ``code`` or ``code-block`` directive. While you can use
+these two directives interchangeably, the ``code-block`` directive offers more flexibility
+and control over code block formatting.
+
+Both the ``code`` and ``code-block`` directives support a ``language`` option
+for specifying the programming language that the code is written in. When you specify
+the language, the code block uses the syntax highlighting for this language.
+
+This ``code`` directive shows how to import a function (``my_function``)
+from a Python module (``mylibrary``) and then demonstrates how to use it::
+
+ .. code:: python
+
+ from mylibrary import my_function
+
+ # Usage example
+ result = my_function(42)
+ print(result)
+
+Here is how the preceding code block is rendered in the documentation:
+
+.. code:: python
+
+ from mylibrary import my_function
+
+ # Usage example
+ result = my_function(42)
+ print(result)
+
+This ``code-block`` directive shows how to turn off a log handler::
+
+ .. code-block:: rst
+
+ for handler in design_logger.handlers:
+ if isinstance(handler, logging.FileHandler):
+ handler.close()
+ design_logger.removeHandler(handler)
+
+Here is how the preceding code block is rendered in the documentation:
+
+.. code-block:: rst
+
+ for handler in design_logger.handlers:
+ if isinstance(handler, logging.FileHandler):
+ handler.close()
+ design_logger.removeHandler(handler)
+
+Code blocks can include comments and message strings that you might need to edit.
+Because comments and message strings are more often seen in PY files than in RST
+files, see :ref:`py_code_comments_message_strings` in the section on PY files.
+
+Number lines in a code block
+----------------------------
+
+With the ``code-block`` directive, you can use the optional ``linenos`` attribute
+to generate line numbers for a code block::
+
+ .. code-block::
+ :linenos:
+
+ from __future__ import division
+ import numpy
+
+ def volume(height, radius):
+ pi = 3.14
+ vol = (1.0/3.0) * height * pi * pow(radius,2)
+ return vol
+
+ vol = volume(2.0, 10)
+ print vol, "(m^3)"
+
+Here is how the preceding code block is rendered in the documentation:
+
+.. vale off
+
+.. code-block::
+ :linenos:
+
+ from __future__ import division
+ import numpy
+
+ def volume(height, radius):
+ pi = 3.14
+ vol = (1.0/3.0) * height * pi * pow(radius,2)
+ return vol
+
+ vol = volume(2.0, 10)
+ print vol, "(m^3)"
+
+.. vale on
+
+To set the line where numbering is to start, you can use the optional ``lineno-start``
+attribute, which automatically activates the ``linenos`` attribute::
+
+ .. code-block::
+ :lineno-start: 12
+
+ Some more Python code, with line numbering starting at line 12.
+
+Here is how the preceding code block is rendered in the documentation:
+
+.. code-block::
+ :lineno-start: 12
+
+ Some more Python code, with line numbering starting at line 12.
+
+Emphasize lines of code
+-----------------------
+
+With the ``code-block`` directive, you can use the optional ``emphasize-lines`` attribute
+to emphasize particular lines of code by highlighting them::
+
+ .. code-block:: python
+ :emphasize-lines: 3,5
+
+ def some_function():
+ interesting = False
+ print("This line is highlighted.")
+ print("This line is no highlighted.")
+ print("This line is highlighted.")
+
+Here is how the preceding code block is rendered in the documentation:
+
+.. code-block:: python
+ :emphasize-lines: 3,5
+
+ def some_function():
+ interesting = False
+ print("This line is highlighted.")
+ print("This line is no highlighted.")
+ print("This line is highlighted.")
+
+Define a caption and name for referencing a code block
+------------------------------------------------------
+With the ``code-block`` directive, you can use the optional ``caption`` and ``name``
+attributes to use either the ``ref`` or ``numref`` role to reference this code block from
+elsewhere in your documentation::
+
+ .. code-block:: python
+ :caption: this.py
+ :name: this-py
+
+ print("Explicit is better than implicit.")
+
+Here is how the preceding code block is rendered in the documentation:
+
+.. code-block:: python
+ :caption: this.py
+ :name: this-py
+
+ print("Explicit is better than implicit.")
+
+You then give the ``name`` attribute to the ``numref`` role to create the cross-reference::
+
+ For an example, see :numref:`this-py`.
+
+If you only define the ``name`` attribute, you can use the ``ref`` role to create the
+cross-reference providing that you explicitly provide the display text for the link::
+
+ For an example, see :ref:`this code snippet `.
+
+Include code files
+------------------
+
+You can use the ``literalinclude`` directive to include a file containing plain
+text as a code block in your documentation. For example, this directive includes a Python
+file named ``example_code.py`` in your documentation::
+
+ .. literalinclude:: example_code.py
+
+Like the ``code-block`` directive, the ``literalinclude`` directive supports the
+``linenos`` attribute to switch on line numbers, the ``lineno-start`` attribute
+to set the line to start the numbering at, the ``emphasize-lines`` attribute to emphasize
+particular lines, and the ``name`` attribute to provide an implicit target name.
+
+For more information, see `Showing code examples `_ in the
+Sphinx documentation on directives.
diff --git a/doc/source/content-writing/rst-files-writers/doc-links.rst b/doc/source/content-writing/rst-files-writers/doc-links.rst
new file mode 100644
index 000000000..3d05725c8
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/doc-links.rst
@@ -0,0 +1,308 @@
+.. _doc_links:
+
+Links
+=====
+
+A link consists of some explicit markup with a *named target* that is either
+internal or external to your project. You can also create a link for downloading
+a file or for going to the description of a Python object in your API reference
+documentation.
+
+.. _doc_links_internal:
+
+Internal links
+--------------
+
+You use the ``ref`` role to link to a target that you place before a heading.
+This allows Sphinx to use the heading as the display text for the link, thereby
+reducing maintenance if the heading later changes.
+
+You first insert the target in the RST file before the heading that you want
+to link to. The target consists of these parts:
+
+- An explicit markup start (``..``) followed by a space
+- An underscore followed by the target name and a colon
+
+Always insert blanks lines both before and after the target.
+
+Here is the target for :ref:`Ansys_Python_Manager` in this guide::
+
+ .. _Ansys_Python_Manager:
+
+To link to this target from any RST or PY file in this guide, use the
+``ref`` role and the target name within a sentence, surrounding the target name
+in single backticks::
+
+ For more information, see :ref:`Ansys_Python_Manager`.
+
+In the documentation, the display text for the link is the heading that follows this target.
+
+If the target is not placed before a heading, or if you want to customize the display text,
+you must provide the display text::
+
+ This :ref:`open source Python QT app ` streamlines the setup of
+ development environments for people new to the Python ecosystem.
+
+.. _doc_links_external:
+
+External links
+--------------
+
+There are several methods that you can use to link to external targets. The
+simplest way is to specify the display text for the link and a URL directly in
+a sentence::
+
+ For more information on creating NumPy arrays, see
+ `Array creation `_
+ in the NumPy documentation.
+
+The display text for a link should either exactly match the title or heading
+that you are referencing or provide a description of the destination page, as
+specified in `Link text `_ in the
+*Google developer documentation style guide*. As shown in the example sentence,
+you should follow a link with a descriptor that indicates where the
+linked content resides, such as in a product's documentation or on an
+organization's website.
+
+The problem with specifying a URL as a target is that if the URL changes or the
+page is later removed, you must update the URL in every place where it is used. This can
+become quite burdensome if you have many links to the same URL.
+
+To reduce maintenance of external links, you can use one of these methods to link to
+named targets:
+
+- Insert named targets at the bottom of individual RST files. For more information,
+ see :ref:`named_targets_bottom_rst_files`.
+- Insert named targets in a central list file, which is usually the :file:`list.rst`
+ file, in the project's ``doc/source`` directory. For more information, see
+ :ref:`named_targets_link_rst_file`.
+
+.. note::
+ You should choose only one of these methods. If you mix them, you might use
+ the same target name in both an individual RST file and the :file:`list.rst` file,
+ which causes Sphinx to raises errors about duplicated targets when building the
+ documentation.
+
+Guidelines for target names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When naming targets, you must adhere to these guidelines to avoid errors
+that Sphinx might otherwise raise when building the documentation:
+
+- Do not use spaces in target names. Instead, use underscores to separate words.
+ For example, ``_numpy`` is the name of the target that links
+ to the `NumPy website `_.
+- Abbreviate target names however you want. Keep in mind that longer, more
+ descriptive names are easier to find if you ever need to replace them.
+ For example, ``_python_main`` is a better target name for the Python organization
+ than ``_python``.
+- Do not use the same names for both internal and external targets. Varying how the
+ names are capitalized does not cause Sphinx to see them as unique. For example, having an
+ internal target named ``_RST_files`` and an external target named ``_rst_files`` causes
+ Sphinx to raise errors when building the documentation because it sees them as
+ duplicate targets.
+
+.. _named_targets_bottom_rst_files:
+
+Named targets at the bottom of RST files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Assume that you want to add links in a RST file to the websites for `NumPy `_, `SciPy `_,
+and `pandas `_, the "big three" data science packages. At the bottom of
+the RST file, you insert named targets to these websites like this:
+
+.. code:: rst
+
+ .. LINKS AND REFERENCES
+
+ .. _NumPy_link: https://numpy.org/
+ .. _SciPy_link: https://www.scipy.org/
+ .. _pandas_link: https://pandas.pydata.org/
+
+To insert links to these targets in a sentence in the RST file, you surround
+each target name in single backticks and follow it with an underscore:
+
+.. code:: rst
+
+ All PyAnsys libraries are expected be consistent in style and formatting with the
+ libraries for the "big three" data science packages: `NumPy_link`_, `SciPy_link`_, and `pandas_link`_.
+
+When using this named target method, you must add targets to the bottom of every RST file
+where you want to insert links to these targets, which requires much more effort and
+maintenance than if you insert all targets in a central :file:`list.rst` file.
+
+.. _named_targets_link_rst_file:
+
+Named targets in a :file:`list.rst` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add a central RST file in your project's ``doc/source`` directory and have the
+Sphinx configuration file read this file to load all named targets, allowing you to insert
+links to any of these targets in any RST file. Consolidating all targets in one file,
+which is usually the :file:`list.rst` file, can significantly reduce maintenance over
+time.
+
+Set up the Sphinx configuration file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use a :file:`list.rst` file, you must set it up in the Sphinx configuration file
+(``doc/source/conf.py``):
+
+#. Open the :file:`conf.py` file.
+#. Search to see if the ``exclude_patterns`` variable is defined.
+#. If this variable is defined, add this line to the list of files and
+ directories that Sphinx is to ignore when looking for source files::
+
+ ``links.rst,``
+
+#. If this variable is not defined, after the lines configuring
+ ``numpydoc`` and enabling ``numpydoc`` validation, define this variable and add the
+ :file:`links.rst` file::
+
+ exclude_patterns = [
+ "links.rst",
+ ]
+
+ If you do not add the :file:`links.rst` file to the ``exclude_patterns`` variable,
+ Sphinx raises this warning during documentation generation: ``document isn't included in any toctree``.
+
+#. Beneath the ``exclude_patterns`` variable, add these lines to enable the ``rst_epilog``
+ reStructuredText string::
+
+ # 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()
+
+ You might want to look at the `config.py `_ file for PyMAPDL because
+ the ``exclude_patterns`` variable for this project lists many files and directories for
+ Sphinx to ignore when looking for source files. Additionally, the ``rst_epilog``
+ string contains a ``replace`` step that look for a ``VERSION`` variable
+ to easily update targets with the MAPDL version for the latest MAPDL release.
+
+When building the documentation, Sphinx dynamically includes the content in the ``rst_epilog``
+string at the bottom of every RST file. Because this string tells Sphinx to read all targets
+in the :file:`list.rst` file, you are able to link to any of these targets from any RST or PY
+file in the project.
+
+You can use another name for the :file:`list.rst` file or use multiple RST files for organizing
+external links as long as you make the appropriate changes to the lines enabling the
+``rst_epilog`` string.
+
+.. note::
+ When documentation checks run on a PR, Sphinx might indicate some links or link anchors are broken,
+ which results in errors. For more information on resolving these errors, see
+ :ref:`resolve_too_long_lines_broken_links`.
+
+Link to named targets in the :file:`list.rst` file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To link to a named target in the :file:`list.rst` file, you drop the leading underscore in the
+target name and add a trailing underscore after the target name. For example, the :file:`list.rst`
+file for this project includes a target named ``_Style_guide_Sphinx_doc``. To link to this target
+from any RST or PY file in this guide, here is how you insert the link::
+
+ The `Style guide for Sphinx-based documentation `_
+ indicates that lines should be limited to a maximum of 79 characters.
+
+While the link still begins with a single backtick and the display text for the link,
+carats surround the target name and an underscore. Following the closing carat, you must
+have a closing single backtick and another underscore.
+
+For examples of named targets and how to organize them by categories, see the
+:file:`list.rst` file in the ``doc/source`` directory for this project or the
+`PyMAPDL `_ project.
+
+Download links
+--------------
+
+To create a link that downloads a file, you can use either a ``download`` link that specifies
+a URL for the file or the ``download`` role and a named target in the :file:`list.rst` file.
+
+This sentence uses a ``download`` link that specifies the URL to download the PDF file for the
+PyFluent cheat sheet::
+
+ You can `download `_ the PyFluent
+ cheat sheet, which is a one-page reference that provides syntax rules and commands for using PyFluent.
+
+This next sentence uses the ``download`` role and a named target in the :file:`list.rst` file
+for the PyMAPDL project to download the PDF file for the PyMAPDL cheat sheet::
+
+ Download the :download:`PyMAPDL cheat sheet ` to help you to learn PyMAPDL.
+
+.. _API_object_links:
+
+Python object links
+-------------------
+
+To link to Python objects in your API reference documentation, you use Python-specific roles.
+For a list of these roles, see `Cross-referencing Python objects `_ in
+the Sphinx documentation. For descriptions of fundamental Python objects, see :ref:`py_file_format`.
+
+If the role links to a Python object in the same module, you can use only the object name
+in the role (as shown in the first of the following three examples). If the role links to a
+Python object in a different module, you must use the module name and object name in the role
+(as shown in the second and third of the following three examples).
+
+Python uses a period (``.``) to denote submodules. If you need to see where a Python object is
+defined in your documentation, use the GitHub search function. For example, to see where the
+``class Primitives3DLayout`` class is defined in PyAEDT, search its repository for this string:
+
+``class Primitives3DLayout``
+
+Search results indicate that this class is defined in ``pyaedt.modeler.Primitives3DLayout.Primitives3DLayout``.
+
+Examples of Python object links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some examples of how you use Python-specific roles to link to Python objects.
+
+**Example 1**
+
+Assuming that your project is PyAEDT, you can use the ``class`` role to link to the
+``Desktop`` class in the PyAEDT API reference documentation::
+
+ The :class:`pyaedt.Desktop` class initializes AEDT and starts the specified version in
+ the specified mode.
+
+**Example 2**
+
+Assuming that your project is PyMAPDL, you can use the ``func`` role to link to the
+``run_batch()`` function in the PyMAPDL API reference documentation::
+
+ You can use the pool to run a set of pre-generated input files using the
+ :func:`run_batch ` method.
+
+**Example 3**
+
+Also assuming that your project is PyMAPDL, you can use both the ``func`` and
+``attr`` roles to link to the ``nodal_displacement()`` function and then the
+``selected_nodes`` attribute in the PyMAPDL API reference documentation::
+
+ If you have subselected a certain component and want to also limit the result of a certain output
+ (:func:`nodal_displacement() `), use the
+ :attr:`selected_nodes ` attribute to get a
+ mask of the currently selected nodes.
+
+More examples of Python object links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To see more examples of how to use Python-specific roles to link to Python objects
+in your API reference documentation, use the GitHub search feature to find the following
+strings in the repositories for PyAnsys libraries, keeping in mind that only some subset
+of these roles is likely used in any library:
+
+- ``mod``
+- ``func``
+- ``data``
+- ``const``
+- ``class``
+- ``meth``
+- ``attr``
+- ``exc``
+- ``obj``
+
+To learn how you can also use Python-specific roles to link to Python objects in the
+Sphinx documentation for other projects, see :ref:`links_to_objects_in_other_doc`.
diff --git a/doc/source/content-writing/rst-files-writers/images.rst b/doc/source/content-writing/rst-files-writers/images.rst
new file mode 100644
index 000000000..223210f83
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/images.rst
@@ -0,0 +1,74 @@
+.. _images:
+
+Images
+======
+
+You use the ``image`` or ``figure`` directive to add an image to
+a RST file.
+
+Both directives support these types of image files: PNG, JPG, and GIF.
+
+While these two directives are similar, the ``figure`` directive supports adding
+a label and a caption for the image, where the label can be used for cross-referencing
+in your documentation.
+
+For either directive, the setup is the same:
+
+#. Place the image file in your library's ``doc/source/_static`` directory.
+#. Place the directive in your RST file where you want the image to appear,
+ using the relative path to this image file in the ``image`` or ``figure``
+ directive.
+
+Add an image using the ``image`` directive
+-----------------------------------------------
+
+When you use the ``image`` directive to add an image, you only need to specify the path
+to the image file. However, specifying the optional ``alt`` attribute, which provides text for
+the image, is strongly recommended::
+
+ .. image:: ..//_static/image1.png
+ :alt: Example first image
+
+This next ``image`` directive provides all optional attributes::
+
+ .. image:: ..//_static/image2.png
+ :width: 300
+ :height: 200
+ :alt: Example second image
+ :align: center
+
+Here are descriptions of all optional attributes for the ``image`` directive:
+
+- ``width`` and ``height``: Control the width and height of the image in pixels.
+ You can specify one of these attributes to maintain the aspect ratio, or specify
+ both attributes to set specific dimensions.
+- ``alt``: Provides text for the image. This attribute is used for accessibility
+ and should provide a concise description of the image content. It is also displays
+ if the image fails to load.
+- ``align``: Controls the horizontal alignment of the image. Options are ``left``,
+ ``right``, and ``center``. If omitted, the image is left-aligned.
+
+Add an image using the ``figure`` directive
+------------------------------------------------
+
+When you use the ``figure`` directive to add an image, you can specify the ``name``
+attribute and a caption. The ``name`` attribute is a custom label that can
+be used to cross-reference the image in your documentation. The caption provides
+context or explanations.
+
+Here is an example of a ``figure`` directive::
+
+ .. figure:: ..//_static/image3.png
+ :figwidth: 300
+ :alt: Example figure
+ :name: custom-label
+
+ You add the caption here.
+
+To reference this image elsewhere in your documentation, use the custom label defined
+for the ``name`` attribute::
+
+ For the plot of the temperatures, see :ref:`custom-label`.
+
+This creates a reference to the image where the ``name`` attribute is defined as ``custom-label``.
+Sphinx displays this image with its caption and specified label in the rendered documentation.
diff --git a/doc/source/content-writing/rst-files-writers/index.rst b/doc/source/content-writing/rst-files-writers/index.rst
new file mode 100644
index 000000000..f9fc95546
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/index.rst
@@ -0,0 +1,139 @@
+.. _rst_files_writers:
+
+Content in RST files
+####################
+
+reStructuredText, a plaintext markup language, uses simple and intuitive
+constructs to indicate the structure of a document. You use reStructuredText (RST)
+files to define the hierarchy of your documentation and provide manually authored
+content.
+
+This page describes the setup of RST files for PyAnsys documentation. It also
+describes the option for using either a RST or Markdown (MD) file as the README
+for the GitHub repository of a PyAnsys project.
+
+For resources related to RST and MD files, see :ref:`style_format_resources`.
+To learn how RST files for PyAnsys libraries are formatted, see :ref:`rst_file_formatting`.
+
+RST file setup
+--------------
+
+In a repository, the ``doc`` directory contains an ``index.rst`` file that defines
+the overall hierarchy (major sections) of the documentation. Each referenced child
+directory has its own ``index.rst`` file. Its first-level heading is the name
+of the documentation section. Documentation for a PyAnsys client library generally has
+five sections:
+
+- Getting started
+- User guide
+- API reference
+- Examples
+- Contribute
+
+In addition to providing the section name, the ``index.rst`` file includes the
+``toctree`` directive to specify how to build and display the content
+for this section.
+
+.. note::
+ A directive is a generic block of explicit markup that sets off a specific block
+ of text. For more information, see `Directives `_ in the
+ Sphinx documentation.
+
+For example, here is the ``toctree`` directive in the ``index.rst`` file for
+this **Content in RST files** section::
+
+ .. toctree::
+ :maxdepth: 3
+ :hidden:
+
+ rst-file-formatting
+ rst-format-rules
+ notices
+ doc-links
+ code-blocks
+ images
+ tables
+ cards
+ tab-sets
+
+The ``maxdepth`` attribute of the ``toctree`` directive specifies the maximum number of
+heading levels to show in the documentation's right pane, labeled **On this page**. In this
+guide, the ``maxdepth`` attribute is set to ``3`` for all sections. The ``toctree`` directive
+then includes an ordered list of the RST files to show in the **Section Navigation** pane. The
+RST extensions for the files in this list are omitted.
+
+To see the ``toctree`` directives for the other sections in this guide,
+in the project's `repository `_, go to the ``doc/source``
+directory and look at the ``index.rst`` files in the child directories for the
+documentation sections.
+
+For more information on RST file setup, see :ref:`rst_files_developers` and
+`Getting Started `_ in the Sphinx documentation.
+
+.. _readme_files:
+
+README file
+-----------
+
+Each PyAnsys repository has a README file in its root directory. This file explains the
+project and points readers to key documentation. The README file can be an RST file
+or a GitHub Flavored Markdown (MD) file. While RST and MD files are similar, the syntax
+differs. If the README file in your repository is an MD file, see
+`GitHub Flavored Markdown Spec `_
+and `Using Markdown and Liquid in GitHub Docs `_.
+
+If your README file is an RST file, you can reuse content in it in the overall ``index.rst``
+file for a library's documentation. However, you cannot reuse content if your README file
+is an MD file. Thus, the disadvantages of having to use a different syntax in the MD file and the
+inability to reuse this MD file on the initial page of your documentation may influence you to
+use an RST file for your README file.
+
+To reuse all content from a ``README.rst`` file in the overall ``index.rst`` file for your
+documentation, use the ``include`` directive::
+
+ .. include:: ../../README.rst
+
+To reuse only a portion of the content in the ``README.rst`` file, use this directive's ``start-line``
+and ``end-line`` attributes::
+
+ .. include:: ../../README.rst
+ :start-line: 4
+ :end-line: 72
+
+Using the preceding attributes necessitates having to change the line numbers
+if content is later added to or removed from the ``README.rst`` file. Thus, you
+might want to use this directive's ``start-after`` attribute instead. It allows
+you to reuse content from a given point to the end of the file.
+
+You first insert a target in the ``README.rst`` file where you want to start the reuse.
+For example, assume that the ``README.rst`` file has an "Overview" section where you want the reuse
+to begin. Before this section, insert a target like this, followed by a blank line::
+
+ .. reuse_start
+
+In the overall ``index.rst`` file for your library's documentation, now insert an ``include``
+directive with a ``start-after`` attribute that specifies this target::
+
+ .. include:: ../../README.rst
+ :start-after: .. reuse_start
+
+If your ``README.rst`` file has links to sections or pages in the library's documentation, you must
+use external links. You can use either URLs or named targets. However, named targets must be inserted
+at the bottom of the ``README.rst`` file. If your project has a central ``links.rst``
+file in the project's ``doc/source`` directory, inserting named targets for links in the
+``README.rst`` file does not work because the GitHub renderer is unaware of this ``links.rst`` file.
+For more information, see :ref:`doc_links_external`.
+
+.. toctree::
+ :maxdepth: 3
+ :hidden:
+
+ rst-file-formatting
+ rst-format-rules
+ notices
+ doc-links
+ code-blocks
+ images
+ tables
+ cards
+ tab-sets
diff --git a/doc/source/content-writing/rst-files-writers/notices.rst b/doc/source/content-writing/rst-files-writers/notices.rst
new file mode 100644
index 000000000..e8f23d69c
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/notices.rst
@@ -0,0 +1,98 @@
+.. _notices:
+
+Notices
+=======
+
+In the *Google developer documentation style guide*, the
+`Notes, cautions, warnings, and other notices `_
+page explains how notices offset important information. In addition to defining
+types, it explains when notices should be used. Avoid overuse because notices
+lose their visual distinctiveness if a page has multiple notices or two (or more)
+consecutive notices.
+
+PyAnsys documentation uses these admonition directives for common notices:
+
+- ``note``
+- ``caution``
+- ``warning``
+- ``important``
+- ``tip``
+
+Note example
+------------
+Here is a formatting example for a ``note`` directive::
+
+ .. note::
+ Some examples require additional Python packages. Ensure
+ that you have these packages installed.
+
+Here is how this note is rendered in the documentation:
+
+.. note::
+ Some examples require additional Python packages. Ensure
+ that you have these packages installed.
+
+Caution example
+---------------
+Here is a formatting example for a ``caution`` directive::
+
+ .. caution::
+ To ensure proper operation, modify this XML file carefully.
+ All paths specified in this file must adhere to the path
+ conventions of the respective operating system.
+
+Here is how this caution is rendered in the documentation:
+
+.. caution::
+ To ensure proper operation, modify this XML file carefully.
+ All paths specified in this file must adhere to the path
+ conventions of the respective operating system.
+
+Warning example
+---------------
+Here is a formatting example for a ``warning`` directive::
+
+ .. warning::
+ This method requires `NumPy `_` to be installed on your machine.
+
+Here is how this warning is rendered in the documentation:
+
+.. warning::
+ This method requires `NumPy `_` to be installed on your machine.
+
+Important example
+-----------------
+Here is a formatting example for an ``important`` directive::
+
+ .. important::
+ Net tracing is a critical requirement for using the ``auto_compoments``
+ definition type when defining components on the die.
+
+Here is how this important notice is rendered in the documentation:
+
+.. important::
+ Net tracing is a critical requirement for using the ``auto_compoments``
+ definition type when defining components on the die.
+
+Tip example
+-----------
+
+Here is a formatting example for a ``tip`` directive::
+
+ .. tip::
+ When you are viewing PyAnsys documentation, the right navigation pane typically
+ displays **Edit on GitHub** and **Show Source** links. For information on
+ using the **Edit on GitHub** link to use the GitHub web editor to submit
+ suggested changes to a page in a PR, see :ref:`edit_on_GitHub`. For information
+ on using the **Show Source** link to see how a page's source file is formatted and
+ how you can reuse this content, see :ref:`rst_file_examples`.
+
+Here is how this tip is rendered in the documentation:
+
+.. tip::
+ When you are viewing PyAnsys documentation, the right navigation pane typically
+ displays **Edit on GitHub** and **Show Source** links. For information on
+ using the **Edit on GitHub** link to use the GitHub web editor to submit
+ suggested changes to a page in a PR, see :ref:`edit_on_GitHub`. For information
+ on using the **Show Source** link to see how a page's source file is formatted and
+ how you can reuse this content, see :ref:`rst_file_formatting`.
diff --git a/doc/source/content-writing/rst-files-writers/rst-file-formatting.rst b/doc/source/content-writing/rst-files-writers/rst-file-formatting.rst
new file mode 100644
index 000000000..6edce5663
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/rst-file-formatting.rst
@@ -0,0 +1,28 @@
+.. _rst_file_formatting:
+
+RST file formatting
+===================
+
+The easiest and best way to understand how to format a RST file is to use the **Show Source**
+link in the right navigation pane of a PyAnsys documentation page. Clicking this link
+displays a text (TXT) version of the page's source file, where you can see the formatting.
+To reuse any content, copy it from the TXT version and paste it directly into one of your RST files,
+modifying it as necessary.
+
+.. caution::
+ You do not want to copy content from the TXT version of an API documentation page
+ because this content is not manually authored in a RST file but rather automatically
+ generated from a PY file.
+
+To view the TXT version for this documentation page, click the **Show Source** link.
+When you finish viewing the TXT version, click your browser's back arrow to return to
+the documentation page.
+
+If you want to view the TXT version of a richly formatted page in the PyFluent documentation,
+read through and then perform these steps:
+
+#. Go to the `Frequently asked questions `_ page in the PyFluent documentation.
+#. In the right navigation pane, click the **Show Source** link to open the TXT version.
+#. View the formatting for this page.
+#. When finished, click your browser's back arrow to return to the PyFluent documentation page.
+#. Click your browser's back arrow once again to return to the developer guide's documentation page.
diff --git a/doc/source/content-writing/rst-files-writers/rst-format-rules.rst b/doc/source/content-writing/rst-files-writers/rst-format-rules.rst
new file mode 100644
index 000000000..3c10dc27f
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/rst-format-rules.rst
@@ -0,0 +1,131 @@
+.. _rst_formatting_rules:
+
+RST formatting rules
+====================
+
+This page provides a summary of RST formatting rules to help you ensure that your
+PyAnsys documentation renders correctly. For a summary of the most important
+writing guidelines, frequently review the `Highlights `_
+page in the *Goggle developer documentation style guide*.
+
+- Use sentence case for headings and titles in PyAnsys documentation, as specified
+ in `Headings and titles `_ in the *Google developer
+ documentation style guide*.
+
+- Underline (and optionally overline) titles to indicate the heading hierarchy.
+ The string of characters indicating the title level should be the same length
+ as the title and must be at least as long as the title. You should have only
+ one top-level heading per RST file. For consistency within PyAnsys libraries,
+ the use of these characters is recommended but not enforced:
+
+ - For section-level headings, use ``###``.
+ - For subsection-level headings, use ``===``.
+ - For subsubsection-level headings, use ``---``.
+ - For subsubsubsection-level headings, use ``~~~``.
+ - For paragraph-level headings, use ``+++``.
+
+- Use blank lines to separate text into paragraphs.
+
+- Ensure that there are no blank spaces at the end of a line. (Running ``pre-commit``
+ finds and removes any trailing white spaces, saving you from seeing errors
+ when you create or push changes to a PR. For more information, see :ref:`run_precommit`.)
+
+- As in Python, indentation is significant. All lines of the same paragraph must be left-aligned to the
+ same level of indentation. Use spaces (and not tabs) for indentation.
+
+- Do not exceed the maximum number of characters per line specified for your PyAnsys
+ library. While the `Style guide for Sphinx-based documentation `_
+ indicates that lines should be limited to a maximum of 79 characters, many PyAnsys
+ libraries extend this limit, sometimes to as many as 120 characters, because
+ today's larger screens can support longer lines.
+
+- Use standard American spelling and punctuation.
+
+- Use "you" and "your" rather then "we" and "our."
+
+- Omit the word "please" and replace the phrase "In order to" with "To."
+
+- Italicize a word or phrase by surrounding it in a single asterisk (``*``) or a
+ single backtick (:code:`\``). In PyAnsys documentation, the following are italicized: words
+ or phrases to be emphasized, first occurrence of a new term, and a publication title
+ that is not a link.
+
+- Bold a word or phrase by surrounding it in double asterisks (``**``). In PyAnsys
+ documentation, the following are in bold: words or phrases to be strongly
+ emphasized and GUI (graphical user interface) components.
+
+- Separate lists from paragraphs with blank links. Begin each item in a bulleted list
+ with either a ``-`` or ``*`` followed by a space. Begin each item in a numbered
+ list with ``#.`` followed by a space. While nested lists are supported, you must
+ separate them from parent list items with blank lines and indent them appropriately.
+
+- For a horizontal list, use the ``hlist`` directive. This directive
+ specifies that list items are to display horizontally in three columns::
+
+ .. hlist::
+ :columns: 3
+
+ * List item 1
+ * List item 2
+ * List item 3
+ * List item 4
+ * List item 5
+
+ This is how the preceding list items, which are in a sublist, are rendered in the
+ documentation:
+
+ .. hlist::
+ :columns: 3
+
+ * List item 1
+ * List item 2
+ * List item 3
+ * List item 4
+ * List item 5
+
+- Indicate a code entity within a paragraph by surrounding it in double backticks
+ (:code:`\`\``). Always follow a code entity with a noun that indicates the object type. In the
+ documentation, a code entity is rendered in a monospaced font within a gray block.
+ (While the `numpydoc Style guide `_ says to
+ surround a code entity in a single backtick, this renders it incorrectly in
+ italics in PyAnsys documentation.) Code entities include the names of Python
+ objects, such as packages, modules, functions, classes, instances, methods, and
+ attributes. In PyAnsys documentation, also surround the following objects
+ in double backticks:
+
+ - File paths
+ - Names of directories, files, and environment variables
+ - Text to type in a command line or in a GUI component
+
+ .. note::
+ Some PyAnsys projects use the ``file`` and ``envvar`` interpretive text
+ roles for names of files and environment variables:
+
+ - :file:`myfile.txt`
+ - :envvar:`MY_ENVAR`
+
+ Roles insert semantic markup in your source files for cross-references to named
+ targets of the type indicated by the role. Because the CSS for the
+ `Ansys Sphinx theme `_ assigns the same semantic markup to
+ the ``file`` role as it does to a filename surrounded in double backticks, it
+ does not matter which markup you use.
+
+- Use the ``code`` role to format text as a code entity if surrounding the text in double
+ backticks is problematic because it contains characters that cause regular
+ expression errors. For example, in this sentence describing the use of double backticks,
+ the ``code`` role had to be used to format the double backticks as a code entity::
+
+ Indicate a code entity within a paragraph by surrounding it in double backticks
+ (:code:`\`\``).
+
+ If you want, you can use the ``code`` role within any sentence to identify small
+ pieces of inline code, individual identifiers (like function names or variable names),
+ or inline code phrases. Most of the time though, using double backticks is easier.
+
+- To create a standalone code block within your documentation, use either the
+ ``code`` or ``code-block`` directive. For more information on code blocks,
+ see :ref:`code_blocks`.
+
+Subsequent pages describe how to use other common Sphinx roles and directives. For
+comprehensive lists of roles and directives, see `Roles `_ and
+`Directives `_ in the Sphinx documentation.
diff --git a/doc/source/content-writing/rst-files-writers/tab-sets.rst b/doc/source/content-writing/rst-files-writers/tab-sets.rst
new file mode 100644
index 000000000..da062cfe1
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/tab-sets.rst
@@ -0,0 +1,36 @@
+.. _tab_sets:
+
+Tab sets
+========
+
+Tab sets are like cards in that they provide for quickly accessing
+information that you are specifically interested in. In PyAnsys
+documentation, tab sets are often used to provide procedures or commands
+for different operating systems.
+
+.. note::
+ To use tab sets in your PyAnsys documentation, you must install
+ and configure the `sphinx-design `_
+ extension. For more information, see :ref:`add_sphinx_extensions`.
+
+ To see and use the tab sets that are shown only as images on this page,
+ see :ref:`setting_up_dev_environment`. To see how the tab sets on this
+ page are formatted, click the **Show Source** link in the page's right pane.
+ As described in :ref:`rst_file_formatting`, you can copy content from the
+ TXT version of this file and then paste it directly into one of your RST files
+ for reuse, modifying it as needed.
+
+Here is an image of a tab set with tabs for installing Python on machines running different
+operating systems. When you click a tab, the procedure for the selected operating system
+is shown.
+
+.. image:: ..//_static/tab-set-single-dev-guide.png
+ :alt: Tab set for installing Python on different operating systems
+
+Here is an image of a tab set with two rows. In the top row, you click the tab for your operating
+system. In the bottom row, you click the tab for the shell that you want to run the
+command in (if more than one shell is available). You can then copy this command and
+paste it in the shell's command line.
+
+.. image:: ..//_static/tab-set-double-dev-guide.png
+ :alt: Tab sets for creating virtual environments on different operating systems using different shells
diff --git a/doc/source/content-writing/rst-files-writers/tables.rst b/doc/source/content-writing/rst-files-writers/tables.rst
new file mode 100644
index 000000000..91cb1eca2
--- /dev/null
+++ b/doc/source/content-writing/rst-files-writers/tables.rst
@@ -0,0 +1,184 @@
+.. _tables:
+
+Tables
+======
+
+You can create four different types of tables in RST files:
+
+- Grid tables: Create by drawing them.
+- Simple tables: Create with the ``table`` directive.
+- CSV tables: Create with the ``csv_table`` directive.
+- List table: Create with the ``list-table`` directive.
+
+The data in a table is always left-aligned. For all table types, you can
+use reStructuredText syntax to format content and add links within the
+table cells.
+
+All tables created with directives support a title and optional attributes.
+For more information, see `Tables `_ in
+the section on reStructuredText directives in the `Docutils `_
+documentation.
+
+Create a grid table
+-------------------
+
+You create a grid table by using plus (``+``), hyphen (``-``), and pipe or
+vertical bar (``|``) characters to "draw" the table. You can also use the
+equal sign (``=``) character to bold the column header text.
+
+Here is a grid table with bold column header text::
+
+ +-------------------+-------------------+-------------------+
+ | Column A | Column B | Column C |
+ | | | |
+ +===================+===================+===================+
+ | Data 1 | Data 2 | Data 3 |
+ +-------------------+-------------------+-------------------+
+ | Data 4 | Data 5 | Data 6 |
+ +-------------------+-------------------+-------------------+
+
+Here is how this grid table is rendered in the documentation:
+
++-------------------+-------------------+-------------------+
+| Column A | Column B | Column C |
+| | | |
++===================+===================+===================+
+| Data 1 | Data 2 | Data 3 |
++-------------------+-------------------+-------------------+
+| Data 4 | Data 5 | Data 6 |
++-------------------+-------------------+-------------------+
+
+The length of the hyphen characters in each column determines the column width.
+For example, assume that you want a table with a wider first column and, in the
+second row, you want the data for the second column to span the third column.
+You would add more hyphen characters in the corresponding header cell and, in the
+second row, remove the pipe character indicating the column break between the second
+and third columns::
+
+ +---------------------------------------+-----------------+----------------+
+ | Calumn A for wider first column | Column B | Column C |
+ +=======================================+=================+================+
+ | Data 1 | Data 2 | Data 3 |
+ +---------------------------------------+-----------------+----------------+
+ | Data 4 | Data 5 with spanning text |
+ +---------------------------------------+----------------------------------+
+ | Data 6 | Data 7 | Data 8 |
+ +---------------------------------------+-----------------+----------------+
+
+Here is how this grid table is rendered in the documentation:
+
++---------------------------------------+-----------------+----------------+
+| Column A for wider first column | Column B | Column C |
++=======================================+=================+================+
+| Data 1 | Data 2 | Data 3 |
++---------------------------------------+-----------------+----------------+
+| Data 4 | Data 5 with spanning text |
++---------------------------------------+-----------------+----------------+
+| Data 6 | Data 7 | Data 8 |
++---------------------------------------+-----------------+----------------+
+
+Create a simple table
+---------------------
+
+You create a simple table using the ``table`` directive.
+
+Here is a ``table`` directive for a simple table, where
+column widths are automatically adjusted to fill the page based
+on their content::
+
+ .. table:: **Table title**
+ :widths: auto
+
+ +-------------+-------------+-------------+
+ | Column A | Column B | Column C |
+ +=============+=============+=============+
+ | Data 1 | Data 2 | Data 3 |
+ +-------------+-------------+-------------+
+ | Data 4 | Data 5 | Data 6 |
+ +-------------+-------------+-------------+
+
+Here is how this simple table is rendered in the documentation:
+
+.. table:: **Table title**
+ :widths: auto
+
+ +-------------+-------------+-------------+
+ | Column A | Column B | Column C |
+ +===========+=+=============+=============+
+ | Data 1 | Data 2 | Data 3 |
+ +-------------+-------------+-------------+
+ | Data 4 | Data 5 | Data 6 |
+ +-------------+-------------+-------------+
+
+Create a CSV table
+------------------
+
+You create a CSV table using the ``csv_table`` directive. When using this
+directive, you must be careful with the placement of commas (``,``).
+When defining the column names and data, you must place a comma immediately
+after the closing quotation marks. You must also place only one space between
+each value. This directive provides no control over the merging of cells.
+However, it does provide the ``widths`` attribute for specifying the width of
+each column as a percentage.
+
+Here is a ``csv_table`` directive that creates a table with three columns
+and two rows, where the second and third columns are three times the width of the
+first column::
+
+ .. csv-table:: **Table title**
+ :header: "Column A", "Column B", "Column C"
+ :widths: 10, 30, 30
+
+ "Data 1", "Data 2", "Data 3"
+ "Data 4", "Data 5", "Data 6"
+
+Here is how this CSV table is rendered in the documentation:
+
+.. csv-table:: **Table title**
+ :header: "Column A", "Column B", "Column C"
+ :widths: 10, 30, 30
+
+ "Data 1", "Data 2", "Data 3"
+ "Data 4", "Data 5", "Data 6"
+
+Create a list table
+-------------------
+
+You create a list table using the ``list-table`` directive. When using this directive,
+you provide the table data in a *uniform* two-level bulleted list, where uniform means
+that each sublist (second-level list) must contain the same number of items. This directive
+uses asterisk (``*``) and hyphen (``-``) characters to define the table structure. When no
+value is specified for the ``widths`` attribute, ``auto`` is the default.
+
+This example of the ``list-table`` directive uses the ``widths`` attribute to specify
+the widths of columns as percentage values::
+
+ .. list-table:: **Table title**
+ :widths: 15 35 50
+ :header-rows: 1
+
+ * - Column A
+ - Column B
+ - Column C
+ * - Data 1
+ - Data 2
+ - Data 3
+ * - Data 4
+ - Data 5
+ - Data 6
+
+Here is how this list table is rendered in the documentation:
+
+.. list-table:: **Table title**
+ :widths: 15 35 50
+ :header-rows: 1
+
+ * - Column A
+ - Column B
+ - Column C
+ * - Data 1
+ - Data 2
+ - Data 3
+ * - Data 4
+ - Data 5
+ - Data 6
diff --git a/doc/source/doc-style/code/sample_func.py b/doc/source/doc-style/code/sample_func.py
index 735fccdb2..69ef2c056 100644
--- a/doc/source/doc-style/code/sample_func.py
+++ b/doc/source/doc-style/code/sample_func.py
@@ -6,7 +6,7 @@ def func(arg1, arg2):
of the function.
.. warning::
- Use the ``.. warning::`` directive within the docstring for any
+ Use the ``warning`` directive within the docstring for any
warnings that need to be explicitly stated. For example, you
want to include a warning for a method that is to be deprecated
in the next release.
diff --git a/doc/source/doc-style/doc-configuration.rst b/doc/source/doc-style/doc-configuration.rst
index 0d5aa56bc..580ebf165 100644
--- a/doc/source/doc-style/doc-configuration.rst
+++ b/doc/source/doc-style/doc-configuration.rst
@@ -63,8 +63,3 @@ The following code collects the required options and automation rules for the
``make.bat`` program to use when building documentation for a PyAnsys project:
.. literalinclude:: code/required_make.bat
-
-
-.. LINKS & REFERENCES:
-
-.. _Sphinx: https://www.sphinx-doc.org/en/master/
diff --git a/doc/source/doc-style/docstrings.rst b/doc/source/doc-style/docstrings.rst
index 8e6e9e965..eb8d87164 100644
--- a/doc/source/doc-style/docstrings.rst
+++ b/doc/source/doc-style/docstrings.rst
@@ -1,3 +1,5 @@
+.. _numpy_docstrings:
+
Numpydoc docstrings
===================
@@ -21,14 +23,15 @@ classes, methods, and variables. For example::
"""Initialize the ``Desktop`` class with the version of AEDT to use."""
.. note::
+
The PyAnsys style uses two backticks to surround the names of classes, methods, and
- variables, not the single backtick that is recommended by `numpydoc`_
+ variables, not the single backtick that is recommended by the numpydoc
style.
Required docstring sections
---------------------------
-PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum:
+PyAnsys library docstrings contain these numpydoc sections as a minimum:
* `Short Summary `_
* `Extended Summary `_ if applicable
@@ -48,8 +51,7 @@ or function to briefly describe what the class or function does. The
raises an error.
The short summary can be declared on the same line as the opening quotes or on
-the next line. While `PEP 257
-`_ accepts both ways, you must be consistent across your
+the next line. While `PEP 257 `_ accepts both ways, you must be consistent across your
project. If you decide to declare the short summary on the same line,
refer to :ref:`Numpydoc validation` because ``"GL01"`` checking must be
turned off.
@@ -227,8 +229,8 @@ Here is a sample ``Examples`` section from a Python file for PyAEDT.
Code supplied in an ``Examples`` section must be compliant with the
`doctest `_ format. This allows
-the code to be used through `pytest `_ to
-perform regression testing to verify that the code is executing as expected.
+the code to be used through `pytest`_ to perform regression testing to verify
+that the code is executing as expected.
If the definition of a method or function is updated, the code in the ``Examples`` section
must be updated. Any change within the API without a corresponding change
@@ -272,16 +274,16 @@ Additional directives
Because Python docstrings are written using RST syntax, it is possible to take
advantage of some directives available in this Markup language. Commonly used
-directives include:
+directives follow.
-- ``.. note::`` highlights important information in the rendered documentation.
+- ``note``: Highlights important information in the rendered documentation.
-- ``.. warning::`` typically points out an action that might result in data loss.
+- ``warning``: Typically points out an action that might result in data loss.
-- ``.. deprecated:: X.Y.Z`` informs the user about the deprecated status of
+- ``deprecated``: ``X.Y.Z`` informs the user about the deprecated status of
the object or feature.
-You can find additional information and examples at `numpydoc`_. Reference
+You can find additional information and examples in the numpy doc. Reference
this documentation as the primary source regarding docstring styles for directives
that are not covered here.
@@ -293,7 +295,7 @@ Here is a generic docstring example compliant with PyAnsys guidelines:
.. literalinclude:: code/sample_func.py
To include the docstring of a function within Sphinx, you use the
-``autofunction::`` directive:
+``autofunction`` directive:
.. code::
@@ -303,5 +305,4 @@ This directive renders the sample function as:
.. autofunction:: ansys_sphinx_theme.examples.sample_func.func
-.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
.. _googledoc: https://google.github.io/styleguide/
diff --git a/doc/source/doc-style/formatting-tools.rst b/doc/source/doc-style/formatting-tools.rst
index 11e4bb252..44b98773c 100644
--- a/doc/source/doc-style/formatting-tools.rst
+++ b/doc/source/doc-style/formatting-tools.rst
@@ -1,3 +1,5 @@
+.. _doc_style_tools:
+
Documentation style tools
=========================
@@ -29,7 +31,7 @@ The `codespell`_ checks for common misspellings in text files. This implies that
is not limited to Python files but can run checks on any human-readable file.
It is possible to ignore words that are flagged as misspelled. You can specify these words in a
-file that can then be passed to `Codespell` by running:
+file that can then be passed to ``codespell`` by running:
.. code:: bash
@@ -39,7 +41,7 @@ The ``docformatter``
--------------------
The `docformatter`_ automatically formats Python docstrings according
-to `PEP 257`_. To make sure `docformatter`_ wraps your docstrings at a given
+to `PEP 257 `_. To make sure ``docformatter`` wraps your docstrings at a given
number of characters, use the following configuration:
.. code:: bash
@@ -87,7 +89,7 @@ take advantage of the `numpydoc`_ Sphinx extension. Note that this extension
checks only for those objects whose docstrings must be rendered. It is not a
command line tool that checks the style of all docstrings in your source code.
-Because `numpydoc`_ is a Sphinx extension, it must be configured in the
+Because ``numpydoc`` is a Sphinx extension, it must be configured in the
``conf.py`` file. See :ref:`The \`\`doc/\`\` directory`. Start by adding it to the
list of extensions:
@@ -95,7 +97,7 @@ list of extensions:
extensions = ["numpydoc", ...]
-Once the `numpydoc`_ extension is added, you can select which `validation checks
+Once the ``numpydoc`` extension is added, you can select which `validation checks
`_
must be addressed by using the ``numpydoc_validation_checks`` dictionary:
@@ -116,8 +118,8 @@ validation checks
The ``pydocstyle``
------------------
-The `pydocstyle`_ is a tool for checking the compliance of Python docstrings with `PEP
-257`_. Its configuration can be defined in the
+The `pydocstyle`_ is a tool for checking the compliance of Python docstrings with `PEP 257 `_.
+Its configuration can be defined in the
:ref:`the \`\`pyproject.toml\`\` file`.
By default, `pydocstyle`_ matches all ``*.py`` files except those starting with
``test_*.py``. The default configuration should be enough for a PyAnsys project.
@@ -166,18 +168,3 @@ name of the folder.
Address any warnings and issues that display by either editing the
file to fix or adding a term to the ``accept.txt`` file under the
``doc`` folder in ``styles\Vocab\ANSYS``.
-
-
-.. _blacken-docs: https://github.com/asottile/blacken-docs
-.. _interrogate: https://interrogate.readthedocs.io/en/latest/
-.. _docstr-coverage: https://docstr-coverage.readthedocs.io/en/latest/index.html
-.. _docstring-coverage: https://bitbucket.org/DataGreed/docstring-coverage/wiki/Home
-.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
-.. _doctest: https://docs.python.org/3/library/doctest.html
-.. _vale: https://vale.sh/
-.. _PEP 257: http://www.python.org/dev/peps/pep-0257/
-.. _docformatter: https://github.com/PyCQA/docformatter
-.. _codespell: https://github.com/codespell-project/codespell
-.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
-.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
-.. _pydocstyle: https://www.pydocstyle.org/en/stable/
diff --git a/doc/source/doc-style/index.rst b/doc/source/doc-style/index.rst
index fe8571112..0e3efe015 100644
--- a/doc/source/doc-style/index.rst
+++ b/doc/source/doc-style/index.rst
@@ -1,3 +1,5 @@
+.. _doc_style_developers:
+
Documentation style
===================
@@ -23,14 +25,14 @@ The documentation for a PyAnsys library should contain:
* Module, class, method, and function docstrings. See
:ref:`docstrings`.
-* Full gallery of examples. See `PyMAPDL Examples
+* Full gallery of examples. See `PyMAPDL examples
`_.
* General content on installing, using, and contributing.
* Link to the library's documentation from the repository's README file.
To ensure clear and consistent documentation, all PyAnsys libraries are to
follow the guidelines in the `Google developer documentation style guide
-`_. Key guidelines include using:
+`_. Key guidelines include using:
- Sentence case for headings and titles
- Active voice
@@ -38,7 +40,7 @@ follow the guidelines in the `Google developer documentation style guide
- Short, clear sentences
To help you follow the Google guidelines and any custom rules
-developed by Ansys, you can implement `Vale `_.
+developed by Ansys, you can implement `Vale `_.
This command-line tool brings code-like linting to prose. For more
information, see :ref:`Vale`.
diff --git a/doc/source/getting-started/basic.rst b/doc/source/getting-started/basic.rst
index 7ecd5be12..16e764551 100644
--- a/doc/source/getting-started/basic.rst
+++ b/doc/source/getting-started/basic.rst
@@ -2,7 +2,7 @@ PyAnsys project organization
============================
The `PyAnsys `_ project is hosted on GitHub at
-`PyAnsys GitHub organization`_. It contains several repositories with Python
+`Ansys GitHub organization`_. It contains several repositories with Python
libraries that interface with Ansys products or services. To try out a
library, visit one of these links:
@@ -16,10 +16,10 @@ library, visit one of these links:
If you want to create, develop, or contribute to a PyAnsys library,
visit these links:
-* `PyAnsys Developer's Guide `_
-* `Ansys Sphinx Theme Documentation `_
-* `gRPC Hello-world Example `_
-* `Material Example Data `_
+* `PyAnsys developer's guide `_
+* `Ansys Sphinx Theme documentation `_
+* `gRPC Hello-world example `_
+* `Material Example data `_
Using the following tools, developers generate library packages from
PROTO files, create coverage reports, and report on system coverage:
@@ -32,7 +32,7 @@ Quick start guide
-----------------
This is an overview on how to create your own PyAnsys repository in the
-`PyAnsys GitHub organization`_. A repository is generally a project for a
+Ansys GitHub organization. A repository is generally a project for a
particular PyAnsys library.
#. **Create the repository:** Create a repository from the
@@ -43,7 +43,7 @@ particular PyAnsys library.
your product or library. For example, the package name for
PyMAPDL is ``ansys/mapdl/core``. Do the
same renaming in ``setup.py``. Do this as a pull request. In fact, only add
- code as pull requests. Do not push to ``main``.)
+ code as pull requests. Do not push to ``main``.
#. **Add source:** Add your source files to
``ansys//`` or create them. Also add unit tests to
@@ -77,12 +77,3 @@ particular PyAnsys library.
.. todo::
Others like requests, RPC, COM, etc.
-
-.. _PyAEDT: https://github.com/ansys/PyAEDT
-.. _PyMAPDL: https://github.com/ansys/pymapdl
-.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/reporting.html
-.. _pyansys/template: https://github.com/ansys/template
-.. _Creating a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
-.. _repository visibility: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility
-.. _PyAnsys GitHub organization: https://github.com/ansys
-.. _pytest: https://pytest.org/
diff --git a/doc/source/getting-started/componentization.rst b/doc/source/getting-started/componentization.rst
index ff59569ac..1d8a077b4 100644
--- a/doc/source/getting-started/componentization.rst
+++ b/doc/source/getting-started/componentization.rst
@@ -1,3 +1,5 @@
+.. _componentizing:
+
Componentizing Ansys packages
=============================
diff --git a/doc/source/getting-started/index.rst b/doc/source/getting-started/index.rst
index f7e9aabe3..05a18886b 100644
--- a/doc/source/getting-started/index.rst
+++ b/doc/source/getting-started/index.rst
@@ -29,7 +29,7 @@ ecosystem. Examples include:
- Data structures and tables with `pandas `_
- 2D visualization using `matplotlib `_
- 3D visualization using `pyvista `_
-- Advanced scientific computing using `scipy `_
+- Advanced scientific computing using `scipy`_
- Machine learning using `tensorflow `_
.. note::
@@ -47,9 +47,6 @@ ecosystem. Examples include:
componentization
Glossary of abbreviations
-.. _PyAEDT: https://github.com/ansys/PyAEDT
-.. _PyMAPDL: https://github.com/ansys/pymapdl
-
Contributing to this guide
~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/how-to/code/pyansys_logging.py b/doc/source/how-to/code/pyansys_logging.py
index e0e27549c..96faa9180 100644
--- a/doc/source/how-to/code/pyansys_logging.py
+++ b/doc/source/how-to/code/pyansys_logging.py
@@ -36,13 +36,13 @@
class InstanceCustomAdapter(logging.LoggerAdapter):
- """This is key to keep the reference to a product instance name dynamic.
+ """Keeps the reference to a product instance name dynamic.
- If we use the standard approach which is supplying ``extra`` input
- to the logger, we would need to keep inputting product instances
+ If you use the standard approach, which is supplying ``extra`` input
+ to the logger, you would need to keep inputting product instances
every time a log is created.
- Using adapters we just need to specify the product instance we refer
+ Using adapters, you just need to specify the product instance that you refer
to once.
"""
@@ -117,12 +117,12 @@ def _format(self, record):
else:
values = record.__dict__
- # Here we can make any changes we want in the record, for
- # example adding a key.
+ # Here you can make any changes that you want in the record. For
+ # example, adding a key.
- # We could create an if here if we want conditional formatting, and even
+ # You could create an ``if`` here if you want conditional formatting, and even
# change the record.__dict__.
- # Since now we don't want to create conditional fields, it is fine to keep
+ # If you don't want to create conditional fields, it is fine to keep
# the same MSG_FORMAT for all of them.
# For the case of logging exceptions to the logger.
diff --git a/doc/source/how-to/compatibility.rst b/doc/source/how-to/compatibility.rst
index 1ea484ac2..5567610ff 100644
--- a/doc/source/how-to/compatibility.rst
+++ b/doc/source/how-to/compatibility.rst
@@ -11,8 +11,7 @@ issues can occur. Some of the most common cases are:
a given version. This causes forward incompatibility issues.
Though there are different ways to handle these issues, some of the PyAnsys libraries,
-such as `PyMAPDL `_ and
-`PyDPF-Core `_, handle them in
+such as `PyMAPDL`_ and `PyDPF-Core `_, handle them in
the same way. To homogenize implementations in PyAnsys libraries,
following their approach is recommended.
diff --git a/doc/source/how-to/continuous-integration.rst b/doc/source/how-to/continuous-integration.rst
index c404f5726..0156f0771 100644
--- a/doc/source/how-to/continuous-integration.rst
+++ b/doc/source/how-to/continuous-integration.rst
@@ -1,3 +1,5 @@
+.. _continuous_integration:
+
Using continuous integration
============================
@@ -8,8 +10,8 @@ logic.
This process is automated as much as possible to alleviate the developer's workload
and ensure a quick development workflow.
-Because ``PyAnsys`` projects are hosted in `GitHub `_, the
-`GitHub Actions `_ framework is used.
+Because PyAnsys projects are hosted in `GitHub `_, the
+`GitHub Actions`_ framework is used.
Enable GitHub actions
---------------------
diff --git a/doc/source/how-to/contributing.rst b/doc/source/how-to/contributing.rst
index 45b95497d..8fda6914b 100644
--- a/doc/source/how-to/contributing.rst
+++ b/doc/source/how-to/contributing.rst
@@ -1,10 +1,12 @@
+.. _contributing:
+
Contributing
============
-Before contributing to a PyAnsys repository, you must understand the general
-coding paradigms being used for PyAnsys development.
+Before contributing to a PyAnsys library, you must understand the general
+coding paradigms used for PyAnsys development.
-#. Follow the `Zen of Python `__.
+#. Follow the `Zen of Python `_.
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,
@@ -28,7 +30,7 @@ coding paradigms being used for PyAnsys development.
#. Review the Ansys `Code of Conduct
`_.
-All ``PyAnsys`` projects are hosted in `GitHub `_ in
+All ``PyAnsys`` projects are hosted in `GitHub `_ in
the form of :ref:`Git` repositories. GitHub is a platform that not only provides
storage for projects but also additional features like code reviews or issue
boards.
@@ -44,18 +46,18 @@ Create a GitHub account
-----------------------
To use GitHub, start by creating an account for the platform. Follow the
-`GitHub Join Process `_.
+`GitHub Join Process `_.
For Ansys employees:
-If you would like to join the `Ansys GitHub Organization `_, visit `Join Ansys GitHub Organization `_.
+If you would like to join the Ansys GitHub organization, visit `Join Ansys GitHub Organization `_.
GitHub repository sections
--------------------------
-Once you have a GitHub account and access to the `Ansys` organization,
+Once you have a GitHub account and access to the Ansys GitHub organization,
you are able to interact with the different repositories. While each
-repository contains all tabbed sections that are shown and described below,
+repository contains all tabbed sections in the following list,
your access level determines tabbed sections you can see.
.. figure:: images/github_sections.png
@@ -140,7 +142,7 @@ clone a repository by running:
git clone git@github.com:/.git
-For example, clone the `PyMAPDL `_
+For example, clone the `PyMAPDL`_
project with:
.. code-block:: bash
@@ -186,6 +188,8 @@ You create a branch with:
git checkout -b
+.. _branch_naming:
+
Branch naming conventions
~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/how-to/dns-configuration.rst b/doc/source/how-to/dns-configuration.rst
index 47fbfb1f0..5d084ba59 100644
--- a/doc/source/how-to/dns-configuration.rst
+++ b/doc/source/how-to/dns-configuration.rst
@@ -31,7 +31,7 @@ shows how to create DNS TXT verification elements for GitHub Pages sites.
PyAnsys verified domains
------------------------
-In the `PyAnsys GitHub organization`_, these domains have been verified:
+In the Ansys GitHub organization, these domains have been verified:
* ``pyansys.com``
* ``docs.pyansys.com``
@@ -58,16 +58,16 @@ This is better explained with the following examples:
Case scenario - **protected** subdomain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- Consider that the domain ``docs.pyansys.com`` has been verified for the `PyAnsys GitHub organization`_.
+- Consider that the domain ``docs.pyansys.com`` has been verified for the Ansys GitHub organization.
- This CNAME is requested: ``subdomain.docs.pyansys.com``.
-This CNAME can only be used by repositories inside the `PyAnsys GitHub organization`_.
+This CNAME can only be used by repositories inside the Ansys GitHub organization.
Any attempt by an external user to take over this CNAME is identified and rejected by GitHub.
Case scenario - **vulnerable** subdomain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- The domain ``docs.pyansys.com`` has been verified for the `PyAnsys GitHub organization`_.
+- The domain ``docs.pyansys.com`` has been verified for the Ansys GitHub organization.
- This CNAME is requested: ``subsubdomain.subdomain.docs.pyansys.com``.
This CNAME **can** be used by external users for their repositories. For this reason,
diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst
index 52b8af0a9..23867fe30 100644
--- a/doc/source/how-to/documenting.rst
+++ b/doc/source/how-to/documenting.rst
@@ -1,16 +1,20 @@
+.. _documenting_developers:
+
Documenting
===========
PyAnsys documentation must not only be written but also maintained. If you are
-new to writing developer documentation, see the `Google developer documentation
-style guide `_. It provides
-editorial guidelines for writing clear and consistent developer documentation,
-allowing this guide to supply guidance only specific to PyAnsys library
-documentation.
+new to writing PyAnsys documentation, see the `Google_dev_doc_style_guide`_,
+which provides the general guidelines that you are to follow. This page supplies guidance specific
+to PyAnsys documentation.
+
+.. note::
+ For comprehensive information on contributing new content or revising existing
+ content in PyAnsys documentation, see :ref:`content_writing`.
When writing developer documentation, the relationship between code and
documentation is key. To keep documentation up to date with evolving
-code:
+code, always perform these tasks:
- Minimize the content footprint.
- Write `timeless documentation `_.
@@ -26,10 +30,8 @@ Documentation sources
-The generation of PyAnsys documentation uses `Sphinx
-`__ and an Ansys-branded theme
-(`ansys-sphinx-theme`_) to
-assemble content in:
+The generation of PyAnsys documentation uses `Sphinx`_ and the Ansys-branded Sphinx theme
+(`Ansys_Sphinx_theme_repo`_) to assemble content in:
- Docstrings
- reStructuredText (RST) files
@@ -38,35 +40,35 @@ assemble content in:
Docstrings
~~~~~~~~~~
-Docstrings must be formatted so that Sphinx can parse them. Sphinx provides
+You must format docstrings so that Sphinx can parse them. Sphinx provides
these extensions for docstring formatting:
-- `numpydoc `_
-- `napoleon `_
+- `numpydoc extension `_
+- `napoleon extension `_
Using the ``numpydoc`` extension is preferred because it supports an API
documentation structure with one page per method, providing Python community
-members with documentation like that generated for the `pandas `_
-and `numpy `_ packages. If your API is very linear, you
+members with documentation like that generated for the `pandas`_
+and `numpy`_ packages. If your API is very linear, you
can use the ``napoleon`` extension because it supports a documentation
structure where everything needed to solve a certain problem can be shown on one page.
-The ``numpydoc`` extension provides its own `style guide
-`_ and a `user guide
-`_ that explains how to use the
-extension with Sphinx. The ``napoleon`` extension, which parses both numpydoc and
-Google style docstrings, refers you to the `Google Python Style Guide
+The ``numpydoc`` manual provides explains how to use the extension with Sphinx and
+includes a `style guide `_ . The ``napoleon`` extension,
+which parses both numpydoc and Google style docstrings, refers you to the `Google Python Style Guide
`_.
-Regardless of the extension that you choose for generating documentation, using
-numpy-style docstrings ensures that there is consistency within PyAnsys libraries.
+Regardless of the extension that you choose for generating documentation from docstrings,
+using numpy-style docstrings ensures that there is consistency within PyAnsys libraries.
For more information, see :ref:`Documentation style`.
+.. _rst_files_developers:
+
RST files
~~~~~~~~~
To provide general usage information in your documentation, use your favorite
-editor to create RST (ReStructured Text) files that you then place in :ref:`The \`\`doc/\`\`
+editor to create RST (ReStructuredText) files that you then place in :ref:`The \`\`doc/\`\`
directory`. The ``index.rst`` file in the ``doc/source`` directory
defines the first level of your documentation hierarchy. The ``toctree``
directive (which stands for "table of contents tree") indicates the maximum
@@ -85,7 +87,7 @@ each one of the ``index.rst`` files.
.. code-block:: rst
- Welcome to the Library Documentation
+ Welcome to the library documentation
####################################
This is the content of the root `index.rst` file.
@@ -131,14 +133,15 @@ structure, the index file referenced for each section must be named
After you build documentation locally as described in :ref:`Build
documentation`, the first-level heading in the ``index.rst`` file for each
section is shown as a clickable link in the header of the
-documentation's generated HTML output. For more information on defining a
-documentation structure, see the `Sphinx Getting Started
-`_ guide.
+documentation's generated HTML output. For more information on defining the
+documentation structure, see `Getting Started
+`_ in the Sphinx
+documentation.
Indicating RST titles
+++++++++++++++++++++
-Within RST files, heading titles are to use sentence case per
+Within RST files, heading titles are to use sentence case per the
`capitalization guidelines `_
in the *Google developer documentation style guide*. The line that follows
the heading title must have a string of characters that is the same length
@@ -155,26 +158,25 @@ is recommended for headings but is not enforced:
- For paragraph-level headings, use ``+++``.
For comprehensive syntax information, see the `reStrucutredText Markup Specification
-`_.
+`_.
-Because you need to be familiar with the content in the `PyAnsys Developer's
-Guide `_, explore its HTML pages and then the RST files
-in its `repository `_. This should help
-you to understand the syntax and see how RST files are nested to create this guide.
+Because you must be familiar with the content in this guide, explore its HTML pages
+and then the RST files in its `repository `_. This should help you
+to understand the syntax and see how RST files are nested to create the guide.
Recommended sections
++++++++++++++++++++
-Although each project is different, documentation has the same goal: providing
-instructions and guidelines for users. Thus, you can find some common sections
-across the documentation for PyAnsys libraries. Try to include these top-level
-sections in your library documentation:
+Although each PyAnsys library is different, its documentation has the same goal:
+provide instructions and guidelines for users. Thus, you can find some common sections
+across the documentation for many PyAnsys libraries. Try to include these top-level
+sections in your library's documentation:
-- ``Getting started`` explains how to install and set up the library.
-- ``User guide`` describes how to use basic features of the library.
-- ``API reference`` documents API resources provided by the library.
-- ``Examples`` provides fully fledged examples for using the library.
-- ``Contributing`` refers to the `PyAnsys developer's guide`_
+- ``Getting started``: Explains how to install and set up the library.
+- ``User guide``: Describes how to use basic features of the library.
+- ``API reference`` Documents API resources provided by the library.
+- ``Examples``: Provides fully fledged examples for using the library.
+- ``Contributing``: Refers to the *PyAnsys developer's guide*
for overall guidance and provides library-specific contribution information.
Examples
@@ -215,7 +217,7 @@ the Python project has the following structure:
└── README.txt (or .rst)
-Enable the Sphinx-Gallery in the Sphinx doc/conf.py file with:
+In the Sphinx configuration file (``doc/conf.py``), enable the ``sphinx-gallery`` exentenion:
.. code:: Python
@@ -235,22 +237,23 @@ to be ``../examples`` and the `output` directory to be ``examples``:
}
Because these examples are
-built using the `Sphinx-Gallery
+built using the `sphinx-gallery
`_ extension, you must
follow its `coding guidelines
`_.
-Using Python, here is a :ref:`General example` using sphinx gallery.
+:ref:`General example` uses Python and the ``sphinx gallery``
+extension.
Document Python code
--------------------
-You can use `sphinx.ext.autodoc` to generate documentation from your Python
+You can use the `sphinx.ext.autodoc` extension to generate documentation from your Python
code. When using this extension, you can include these directives in your :ref:`RST files`:
-* ``automodule`` for documenting modules
-* ``autoclass`` for documenting classes
-* ``autofunction`` for documenting methods and functions
+* ``automodule``: For documenting modules.
+* ``autoclass``: For documenting classes.
+* ``autofunction``: For documenting methods and functions.
For a full list of 'auto' directives, see `Include documentation from docstrings
`_ in the Sphinx
@@ -264,17 +267,17 @@ There are two main ways of using Sphinx to document a class:
* Manually describe 'how' and 'why' you use a class in :ref:`RST files`.
* Automatically generate documentation for classes using the ``autoclass`` or
- ``autosummary`` directive in :ref:`RST files`.
+ ``autosummary`` directive in RST files.
Manually generate documentation
+++++++++++++++++++++++++++++++
-To describe 'why' and 'how' you use a class within :ref:`RST files`, use the
+To describe 'why' and 'how' you use a class within RST files, use the
``code-block`` directive:
.. tab-set::
- .. tab-item:: Doc Source Code
+ .. tab-item:: Doc surce code
.. code-block:: rst
@@ -288,7 +291,7 @@ To describe 'why' and 'how' you use a class within :ref:`RST files`, use the
>>> my_obj.parm1
'apple'
- .. tab-item:: Rendered Doc
+ .. tab-item:: Rendered doc
Initialize ``my_module.MyClass`` with initial parameters. These
parameters are automatically assigned to the class.
@@ -305,8 +308,8 @@ Automatically generate documentation
To automatically generate class descriptions from the numpydoc strings in
your Python files, use either the ``autoclass`` or ``autosummary`` directive
-in your :ref:`RST files`. For information on docstrings and required docstring
-sections, see :ref:`Numpydoc docstrings`.
+in your RST files. For information on docstrings and required docstring
+sections, see :ref:`Numpydoc docstrings`.
For simple classes, use the ``autoclass`` directive:
@@ -325,12 +328,11 @@ For simple classes, use the ``autoclass`` directive:
:members:
-For complex classes with many methods, use the
-``autosummary`` directive:
+For complex classes with many methods, use the ``autosummary`` directive:
.. tab-set::
- .. tab-item:: Doc Source Code
+ .. tab-item:: Doc source code
.. code-block:: rst
@@ -343,7 +345,7 @@ For complex classes with many methods, use the
ansys_sphinx_theme.examples.samples.Complex.imag
ansys_sphinx_theme.examples.samples.Complex.abs
- .. tab-item:: Rendered Doc
+ .. tab-item:: Rendered doc
.. autoclass:: ansys_sphinx_theme.examples.samples.Complex
@@ -353,8 +355,8 @@ For complex classes with many methods, use the
ansys_sphinx_theme.examples.samples.Complex.imag
ansys_sphinx_theme.examples.samples.Complex.abs
-When you use the ``autosummary`` directive, each class has its own dedicated page,
-and each method and attribute in that class also has its own page.
+When you use the ``autosummary`` directive, each class has its own dedicated page.
+Each method and attribute in that class also has its own page.
Document multiple classes
+++++++++++++++++++++++++
@@ -386,14 +388,12 @@ documented separately.
Build documentation
-------------------
-`Sphinx `_ is used to build the documentation.
-You configure the entire build process in the ``conf.py`` file, located in the
-``source/`` directory in :ref:`The \`\`doc/\`\` directory`.
+`Sphinx`_ is used to build the documentation. You configure the entire build process in the
+``conf.py`` file, located in the ``source/`` directory in :ref:`The \`\`doc/\`\` directory`.
This directory also contains a ``Makefile`` file and a ``make.bat`` file for
automating the building process. Different builders render different
-documentation output, such as ``HTML``, ``LaTeX`` or
-``PDF``.
+documentation output, such as ``HTML``, ``LaTeX`` or ``PDF``.
Build HTML documentation
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -477,6 +477,8 @@ The resulting PDF and intermediate LaTeX files are created in the
Because warnings and errors that occur during the LaTeX building and rendering
processes are ignored, it is possible that the PDF file has text formatting errors.
+.. _multi_version_enabling:
+
Enabling multi-version documentation
------------------------------------
@@ -595,7 +597,7 @@ documentation for the first time.
Using the ``{{ secrets.GITHUB_TOKEN }}`` when deploying to another repository is
not possible due to the level of credentials of this token. Instead, use the
-secrets generated by the ``PyAnsy Bot Application``.
+secrets generated by the PyAnsy Bot application.
For deploying the documentation to another repository, use the following
workflow:
@@ -689,7 +691,7 @@ adding the ``dev`` path to the URL as follows:
drop-down button for selecting the desired version should be available in the
top right corner of the documentation's navigation bar.
-For example, consider PyAEDT documentation:
+For example, consider the PyAEDT documentation:
- The URL for documentation of the latest stable release is ``_.
- The URL for documentation of the latest development version is ``_.
@@ -708,8 +710,9 @@ GitHub pull request. For more information, see :ref:`Build documentation`.
Using PyMeilisearch as search engine
------------------------------------
-PyMeilisearch is a Python client library that enables you to utilize MeiliSearch, an open-source search engine,
-to provide fast and relevant search capabilities for your application's data.
+PyMeilisearch is a Python client library that enables you to utilize
+MeiliSearch, an open-source search engine, to provide fast and relevant
+search capabilities for your application's data.
To enable multi-version documentation in your project, follow these steps:
@@ -768,24 +771,5 @@ To enable multi-version documentation in your project, follow these steps:
Replace , , and with appropriate values for your project.
The version of your package is automatically calculated and used for indexing, ensuring that your documentation remains up-to-date.
-For more detailed documentation, refer to the `PyMeilisearch`_ and `ansys-sphinx-theme`_ documentation.
+For more information, see the `PyMeilisearch`_ and `ansys-sphinx-theme-doc`_ documentation.
By following these steps, you can effectively use PyMeilisearch as a search engine for multi-version documentation in your project.
-
-.. Links
-
-.. _GitHub Pages: https://pages.github.com/
-.. _GitHub Actions: https://github.com/features/actions
-.. _PyMAPDL Documentation: https://mapdl.docs.pyansys.com/
-.. _pyansys/pymapdl-docs: https://github.com/ansys/pymapdl-docs
-.. _gh-pages: https://github.com/ansys/dev-guide/tree/gh-pages
-.. _enabling GitHub pages: https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site
-.. _tox: https://github.com/tox-dev/tox
-.. _PyAnsys DNS Zones: https://portal.azure.com/#@ansys.com/resource/subscriptions/2870ae10-53f8-46b1-8971-93761377c38b/resourceGroups/pyansys/providers/Microsoft.Network/dnszones/pyansys.com/overview
-.. _Maxime Rey: https://teams.microsoft.com/l/chat/0/0?users=maxime.rey@ansys.com
-.. _Roberto Pastor Muela: https://teams.microsoft.com/l/chat/0/0?users=roberto.pastormuela@ansys.com
-.. _Alex Kaszynski: https://teams.microsoft.com/l/chat/0/0?users=alexander.kaszynski@ansys.com
-.. _PyAnsys Bot: https://github.com/apps/pyansys-bot
-.. _PyAnsys Organization: https://github.com/ansys
-.. _ansys-templates: https://github.com/ansys/ansys-templates
-.. _PyMeilisearch: https://pymeilisearch.docs.ansys.com/
-.. _ansys-sphinx-theme: https://sphinxdocs.ansys.com/
diff --git a/doc/source/how-to/grpc-api-packages.rst b/doc/source/how-to/grpc-api-packages.rst
index e8444dc38..04e770eca 100644
--- a/doc/source/how-to/grpc-api-packages.rst
+++ b/doc/source/how-to/grpc-api-packages.rst
@@ -16,7 +16,8 @@ Maintain API definition repository
Because the Protobuf definition of the service is language agnostic, the repository
containing the Protobuf files can be created within the top-level
-`Ansys GitHub organization `_.
+`Ansys GitHub organization`_.
+
Every update of the Protobuf files follows a standard
pull request process as a sanity check for API definition accuracy. Language-
specific packages can be generated for each merge or on a set cadence.
@@ -29,20 +30,19 @@ have a dedicated Python package containing the needed ``.proto`` files compiled
Python source code. These are typically consumed by the PyAnsys client libraries
for being able to communicate with their respective services.
-For example, `PyMAPDL `_ consumes the
-``ansys-api-mapdl`` package, which is built in the
-`ansys-api-mapdl repository `_.
+For example, `PyMAPDL_ consumes the ``ansys-api-mapdl`` package, which is built in the
+`ansys-api-mapdl`_ repository.
How to build an ``ansys-api-`` repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `Ansys GitHub organization`_ has a dedicated template repository for creating
+The Ansys GitHub organization has a dedicated template repository for creating
these ``.proto`` file repositories and the needed files to generate the Python API
packages to be consumed by the PyAnsys clients.
-In order to set up an API repository like `ansys-api-mapdl `_,
+To set up an API repository like the `ansys-api-mapdl`` one,
select the `ansys-api-template `_ repository
-when creating a new repository within the `Ansys GitHub organization`_.
+when creating a repository within the Ansys GitHub organization.
Follow the instructions on the `ansys-api-template - Expected usage `_
section to understand how to use the template repository.
@@ -217,8 +217,8 @@ Releasing
As shown in the ``release`` section of GitHub workflow, once the Python
API package is compiled it is then uploaded to the public PyPI. In order to do
so, it is necessary to have access to the ``PYPI_TOKEN`` within the GitHub
-repository. Please contact the PyAnsys Core team at `pyansys.core@ansys.com
-`_ in order to get the needed credentials.
+repository. To get the needed credentials, contact the PyAnsys Core team
+at `pyansys.core@ansys.com `_.
If the repository cannot be uploaded to the public PyPI yet, but your Python
client library needs to consume this Python API package, it can also be
@@ -300,6 +300,6 @@ main reasons behind are:
repository private since all users which consume the Python API package have direct access
to the ``.proto`` files that are in the repository.
-However, before making any repository public with the `Ansys GitHub organization`_, please review
+However, before making any repository public with the `Ansys GitHub organization`_, review
the `Ansys open-source guide documentation `_
to verify that the repository is compliant with all the needed requirements.
diff --git a/doc/source/how-to/releasing.rst b/doc/source/how-to/releasing.rst
index 0eaf21ace..b1953b4ae 100644
--- a/doc/source/how-to/releasing.rst
+++ b/doc/source/how-to/releasing.rst
@@ -31,11 +31,6 @@ packages, `numpy`_, `scipy`_, and `pandas`_, ``MAJOR`` versions of PyAnsys
packages are not released when any incompatible API change is made but rather
when major, globally breaking API changes are made.
-.. _Semantic Versioning: https://semver.org/
-.. _numpy: https://numpy.org/
-.. _scipy: https://www.scipy.org/
-.. _pandas: https://pandas.pydata.org/
-
Note that ``0.MINOR.PATCH`` packages are expected to have fluid APIs and should
be solidified at the ``1.MINOR.PATCH`` release. At that point, APIs are expected
to be much more stable.
@@ -398,7 +393,7 @@ Replace ```` and ```` with the package name and th
twine-username: "__token__"
twine-token: ${{ secrets.PYPI_TOKEN }}
-.. _GitHub:
+.. _GitHub_releasing:
GitHub
~~~~~~
@@ -518,10 +513,6 @@ public PyPI and GitHub.
python -m pip install path/to/package/wheel.whl
-.. _PyPI: https://pypi.org/
-.. _PyAnsys PyPI: https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi
-.. _PyAnsys: https://github.com/ansys
-.. _pip Documentation: https://pip.pypa.io/en/stable/cli/pip_install/
.. |check| raw:: html
diff --git a/doc/source/how-to/setting-up.rst b/doc/source/how-to/setting-up.rst
index 59e971cd7..bc975e787 100644
--- a/doc/source/how-to/setting-up.rst
+++ b/doc/source/how-to/setting-up.rst
@@ -1,3 +1,5 @@
+.. _setting_up_dev_environment:
+
Setting up your development environment
=======================================
@@ -356,21 +358,21 @@ Signing commits
To verify which code changes were made by you, signing the commit
is required. To sign a commit, you must generate a ``GPG`` key, associate it with
-``GitHub``, and specify it in your ``Git`` :ref:`Configuration`.
+GitHub, and specify it in your ``Git`` :ref:`Configuration`.
-For an explanation of the process, in the ``GitHub`` documentation, see `Verify
+For an explanation of the process, in the GitHub documentation, see `Verify
Commit Signatures `_.
Enabling SSH
~~~~~~~~~~~~
-Working with ``Secure Shell Protocol (SSH)`` is not only a good practice but
-also required for contributing to PyAnsys projects. Without an ``SSH`` key,
+Working with Secure Shell Protocol (SSH) is not only a good practice but
+also required for contributing to PyAnsys projects. Without an SSH key,
you are not able to clone **internal** or **private** repositories or
to push new changes.
-For information on setting up ``SSH`` with ``GitHub``, in the ``GitHub`` documentation,
+For information on setting up SSH with GitHub, in the GitHub documentation,
see `Connecting to GitHub with SSH
`_.
@@ -481,11 +483,11 @@ Windows terminal
The `Windows Terminal `_ is
an app that integrates multiple shells into a single console. Windows
ships by default with two shells: ``CMD`` and ``PowerShell``. If :ref:`WSL2` is
-installed, a Linux shell is added. Hence, the goal of the ``Windows Terminal``
+installed, a Linux shell is added. Hence, the goal of the Windows Terminal
is to collect and manage all shell sessions in a single program.
Installation
~~~~~~~~~~~~
-You can install ``Windows Terminal`` directly from the `official Microsoft Store package
+You can install Windows Terminal` directly from the `official Microsoft Store package
`_.
diff --git a/doc/source/how-to/testing.rst b/doc/source/how-to/testing.rst
index e032540a4..8b397d2da 100644
--- a/doc/source/how-to/testing.rst
+++ b/doc/source/how-to/testing.rst
@@ -1,3 +1,5 @@
+.. _testing:
+
Testing
=======
@@ -25,10 +27,10 @@ Test framework
For consistency, PyAnsys tools and libraries should use either the `unittest
-`_ or `pytest
-`_ framework for unit testing. This last framework is
-recommended unless any constraint in your project prevents you from using it. As
-described in :ref:`Required files`, unit tests should be placed in :ref:`The
+`_ or `pytest`_ framework
+for unit testing. This last framework is recommended unless any constraint
+in your project prevents you from using it. As described in :ref:`Required files`,
+unit tests should be placed in :ref:`The
\`\`tests/\`\` directory` in the library's root directory.
Add testing dependencies
@@ -36,7 +38,7 @@ Add testing dependencies
Requirements for testing dependencies should be included either in :ref:`The
\`\`setup.py\`\` file`, :ref:`The \`\`pyproject.toml\`\` file` or in a
-``requirements_tests.txt`` file. Only ``pytest`` and ``pytest-cov``
+``requirements_tests.txt`` file. Only ``pytest`` and `pytest-cov`_
must be specified as third-party dependencies because``unittest`` is included
in `The Python Standard Library `_.
@@ -426,8 +428,7 @@ Because Python is an interpreted language, syntax errors can only be
caught during the almost trivial compile times. Thus, developers of Python libraries
should aim to have high coverage for their libraries. Coverage is defined as parts
of the executable and usable source that are tested by unit tests. You can use
-the `pytest-cov `_ library to view the
-coverage for your library.
+the `pytest-cov`_ library to view the coverage for your library.
Configure code coverage
~~~~~~~~~~~~~~~~~~~~~~~
@@ -515,7 +516,7 @@ development environment, it is often not possible to enforce testing on
multiple platforms, or even to enforce unit testing in general. However, with the proper
automated CI/CD, such testing can still occur and be enforced automatically.
-`GitHub Actions`_ is the preferred automated CI/CD platform for running Python
+GitHub Actions is the preferred automated CI/CD platform for running Python
library unit tests for PyAnsys. It can be used immediately by cloning the
project `template `_. If you are
unfamiliar with GitHub actions, see `GitHub Actions`_ for an overview.
@@ -524,7 +525,6 @@ unfamiliar with GitHub actions, see `GitHub Actions`_ for an overview.
:language: yaml
-.. _GitHub Actions: https://github.com/features/actions
.. _Test Driven Development (TDD): https://en.wikipedia.org/wiki/Test-driven_development
.. _codecov.io: https://app.codecov.io/gh/pyansys
-.. _poetry: https://python-poetry.org
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a7731104a..c8511448e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -67,4 +67,4 @@
how-to/index
all-styles
abstractions/index
-
+ content-writing/index
diff --git a/doc/source/links.rst b/doc/source/links.rst
new file mode 100644
index 000000000..412fb7b66
--- /dev/null
+++ b/doc/source/links.rst
@@ -0,0 +1,195 @@
+.. If you need to refer to a specific version, replace
+.. the `vXXX` for `%%VERSION%%`.
+.. The substitution for the actual value is made in the Sphinx conf.py file.
+
+.. # Emails
+.. _pyansys_core_email: pyansys.core@ansys.com
+
+.. #content writing resources
+.. _Google_dev_doc_style_guide: https://developers.google.com/style
+.. _Markdown_GitHub_flavored_spec: https://github.github.com/gfm/
+.. _Material_for_Sphinx: https://bashtage.github.io/sphinx-material/basics.html
+.. _Python_doc: https://www.python.org/doc/
+.. _Quick_RST: https://docutils.sourceforge.io/docs/user/rst/quickref.html
+.. _RST_markup_spec: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+.. _RST_markup_syntax_parser: https://docutils.sourceforge.io/rst.html
+.. _RST_primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _Style_guide_Sphinx_doc: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/index.html
+.. _Ansys_Sphinx_theme_repo: https://github.com/ansys/ansys-sphinx-theme
+.. _ansys-sphinx-theme-doc: https://sphinxdocs.ansys.com/
+.. _Ansys_Python_Manager_repository: https://github.com/ansys/python-installer-qt-gui
+.. _Ansys_templates: https://github.com/ansys/ansys-templates
+.. _ansys-templates: https://templates.ansys.com/index.html
+.. _Git: https://git-scm.com/
+
+.. _Git_Extensions: https://gitextensions.github.io/
+.. _Notepadpp: https://notepad-plus-plus.org/
+.. _pip: https://pypi.org/project/pip/
+.. _Python: https://www.python.org/
+.. _Python_glossary: https://docs.python.org/3/glossary.html
+.. _Python_in_VSC: https://code.visualstudio.com/docs/languages/python
+.. _Sphinx: https://www.sphinx-doc.org/en/master/
+.. _Vale: http://vale.sh/
+.. _VSC: https://code.visualstudio.com/
+.. _array_creation: https://numpy.org/doc/stable/user/basics.creation.html
+
+.. #Ansys libraries:
+.. _Ansys_Python_Manager_doc: https://installer.docs.pyansys.com/version/stable/
+.. _dev_guide_repo: https://github.com/ansys/pyansys-dev-guide
+.. _Fluent_faq_page: https://fluent.docs.pyansys.com/version/stable/getting_started/faqs.html
+.. _join_ansys_organization: https://myapps.microsoft.com/signin/8f67c59b-83ac-4318-ae96-f0588382ddc0?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706
+.. _join_ansys_internal_organization: https://myapps.microsoft.com/signin/42c0fa04-03f2-4407-865e-103af6973dae?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706
+.. _Links_for_dev_guide: https://github.com/ansys/pyansys-dev-guide/trr/blob/main/doc/source/links.rst
+.. _Links_for_pymapdl: https://github.com/ansys/pymapdl/blob/main/doc/source/links.rst
+.. _PyAnsys_geometry_Docker_containers: https://geometry.docs.pyansys.com/version/stable/getting_started/docker/index.html
+.. _PyAnsys_landing_page: https://docs.pyansys.com/version/stable/
+.. _python_installer_qt_ui_releases: https://github.com/ansys/python-installer-qt-gui/releases
+.. _PyMAPDL_config: https://github.com/ansys/pymapdl/blob/main/doc/source/conf.py
+.. _pyansys/pymapdl-docs: https://github.com/ansys/pymapdl-docs
+.. _PyMAPDL Documentation: https://mapdl.docs.pyansys.com/
+.. _review_bot: https://github.com/ansys/review-bot
+
+.. #Ansys
+.. _ansys: https://www.ansys.com/
+.. _ansys_help: https://ansyshelp.ansys.com
+
+.. #Other libraries
+.. _Black: https://black.readthedocs.io/en/latest/
+.. _codespell: https://github.com/codespell-project/codespell
+.. _Flake8: https://flake8.pycqa.org/en/latest/
+.. _isort: https://pycqa.github.io/isort/
+.. _numpy: https://numpy.org/
+.. _pandas: https://pandas.pydata.org/
+.. _pre-commit: https://pre-commit.com/
+.. _scipy: https://scipy.org/
+.. _tox: https://tox.wiki/en/latest/
+.. _tox_repo: https://github.com/tox-dev/tox
+.. _make: https://www.gnu.org/software/make/
+
+.. #External links
+.. _Docutils: https://docutils.sourceforge.io/
+.. _doctest: https://docs.python.org/3/library/doctest.html
+.. _Google_docstrings: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
+.. _Notepadpp_downloads: https://notepad-plus-plus.org/downloads/
+.. _Notepadpp_searching: https://npp-user-manual.org/docs/searching/
+.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/index.html
+.. _numpydoc_style_guide: https://numpydoc.readthedocs.io/en/latest/format.html
+.. _numpydoc_style_guide_sections: https://numpydoc.readthedocs.io/en/latest/format.html#sections
+.. _RST_table_directives: https://docutils.sourceforge.io/docs/ref/rst/directives.html#tables
+.. _VSC_doc: https://code.visualstudio.com/Docs
+.. _VSC_doc_setup: https://code.visualstudio.com/docs/setup/setup-overview
+.. _unzip: https://7-zip.org/
+
+.. #Sphinx-related links
+.. _PyData_Sphinx_theme: https://github.com/pydata/pydata-sphinx-theme
+.. _Sphinx_autoapi: https://pypi.org/project/sphinx-autoapi/
+.. _Sphinx_contrib_org: https://github.com/sphinx-contrib/
+.. _Sphinx_ext_sphinx_design: https://sphinx-design.readthedocs.io/en/latest/index.html
+.. _Sphinx_ext_sphinx_gallery: https://sphinx-gallery.github.io/stable/index.html
+.. _Sphinx_ext_sphinx_gallery_structure: https://sphinx-gallery.github.io/stable/syntax.html
+.. _Sphinx_extensions: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
+.. _Sphinx_nbsphinx_extension: https://nbsphinx.readthedocs.io/en/0.9.3/
+.. _Sphinx_nbsphinx_ipykernal_pkg: https://pypi.org/project/ipykernel/
+.. _Sphinx_doc_autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+.. _Sphinx_doc_directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
+.. _Sphinx_doc_directives_code_examples: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples
+.. _Sphinx_doc_ref_Python_objects: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects
+.. _Sphinx_doc_roles: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
+.. _Sphinx_GS_doc: https://www.sphinx-doc.org/en/master/#get-started
+
+.. #Google dev doc guide links:
+.. _Google_dev_doc_articles: https://developers.google.com/style/articles
+.. _Google_dev_doc_headings: https://developers.google.com/style/headings
+.. _Google_dev_doc_highlights: https://developers.google.com/style/highlights
+.. _Google_dev_doc_link_text: https://developers.google.com/style/link-text
+.. _Google_dev_doc_notices: https://developers.google.com/style/notices
+
+.. #GitHub links:
+.. _Join_GitHub: https://github.com/join
+.. _GitHub: https://github.com/
+.. _GitHub_Desktop: https://desktop.github.com/
+.. _GitHub_doc: https://docs.github.com/en
+.. _GitHub_doc_flavored_markdown: https://docs.github.com/en/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs
+.. _Liquid: https://shopify.github.io/liquid/basics/introduction/
+.. _search_GitHub_doc: https://docs.github.com/en/search-github
+.. _two_factor_auth: https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication
+.. _GitHub Pages: https://pages.github.com/
+.. _GitHub Actions: https://github.com/features/actions
+.. _codecov: https://github.com/codecov
+.. _gh-pages: https://github.com/ansys/dev-guide/tree/gh-pages
+.. _enabling GitHub pages: https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site
+.. _Creating a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
+.. _repository visibility: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility
+.. _Ansys GitHub organization: https://github.com/ansys
+
+.. #Python
+.. _Python_Package_Index: https://pypi.org/
+.. _venv: https://docs.python.org/3/library/venv.html
+.. _pytest: https://docs.pytest.org/en/stable/
+.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
+.. _MIT License: https://opensource.org/licenses/MIT
+.. _PEP 8: https://www.python.org/dev/peps/pep-0008/
+.. _PEP8: https://peps.python.org/pep-0008/#introduction
+.. _PEP-257: https://peps.python.org/pep-0257
+.. _PEP 420: https://peps.python.org/pep-0420/
+.. _PEP 517: https://peps.python.org/pep-0517/
+.. _PEP 518: https://peps.python.org/pep-0518/
+.. _native namespace packages: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages
+.. _Namespace packages: https://packaging.python.org/guides/packaging-namespace-packages/
+.. _Python Packaging User Guide: https://packaging.python.org/en/latest/
+.. _Python Packaging Authority: https://www.pypa.io/en/latest/
+.. _PyAnsys: https://docs.pyansys.com/
+.. _PyMAPDL: https://github.com/ansys/pymapdl
+.. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/
+.. _reStructuredText Markup Syntax: https://docutils.sourceforge.io/rst.html
+.. _Markdown Syntax: https://www.markdownguide.org/basic-syntax/
+
+.. _Building and Distributing Packages with Setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
+.. _Configuring setuptools using setup.cfg files: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
+.. _setuptools: https://setuptools.pypa.io/en/latest/index.html
+
+.. _blacken-docs: https://github.com/asottile/blacken-docs
+.. _interrogate: https://interrogate.readthedocs.io/en/latest/
+.. _docstr-coverage: https://docstr-coverage.readthedocs.io/en/latest/index.html
+.. _docstring-coverage: https://bitbucket.org/DataGreed/docstring-coverage/wiki/Home
+.. _doctest: https://docs.python.org/3/library/doctest.html
+.. _docformatter: https://github.com/PyCQA/docformatter
+
+.. _pydocstyle: https://www.pydocstyle.org/en/stable/
+.. _pyansys/template: https://github.com/ansys/template
+
+.. _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
+.. _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
+
+.. _ImportError: https://docs.python.org/3/library/exceptions.html#ImportError
+.. _dunder methods: https://docs.python.org/3/reference/datamodel.html#special-method-names
+
+.. _PyPI: https://pypi.org/
+.. _PyAnsys PyPI: https://pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi
+.. _pip Documentation: https://pip.pypa.io/en/stable/cli/pip_install/
+.. _Semantic Versioning: https://semver.org/
+
+.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
+.. _Flit: https://flit.pypa.io/en/latest/
+.. _flit pyproject.toml guidelines: https://flit.readthedocs.io/en/latest/pyproject_toml.html
+.. _Poetry: https://python-poetry.org/
+.. _poetry pyproject.toml documentation: https://python-poetry.org/docs/pyproject/
+.. _setuptools_repo: https://pypi.org/project/setuptools/
+.. _setuptools metadata fields: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#declarative-config
+
+.. _dependabot: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates
+
+.. _PyAnsys DNS Zones: https://portal.azure.com/#@ansys.com/resource/subscriptions/2870ae10-53f8-46b1-8971-93761377c38b/resourceGroups/pyansys/providers/Microsoft.Network/dnszones/pyansys.com/overview
+.. _Maxime Rey: https://teams.microsoft.com/l/chat/0/0?users=maxime.rey@ansys.com
+.. _Roberto Pastor Muela: https://teams.microsoft.com/l/chat/0/0?users=roberto.pastormuela@ansys.com
+.. _Alex Kaszynski: https://teams.microsoft.com/l/chat/0/0?users=alexander.kaszynski@ansys.com
+.. _PyAnsys Bot: https://github.com/apps/pyansys-bot
+.. _PyAnsys Organization: https://github.com/ansys
+.. _PyMeilisearch: https://pymeilisearch.docs.ansys.com/
diff --git a/doc/source/packaging/build-systems.rst b/doc/source/packaging/build-systems.rst
index d5ae2dc64..f14630522 100644
--- a/doc/source/packaging/build-systems.rst
+++ b/doc/source/packaging/build-systems.rst
@@ -43,41 +43,40 @@ introduced the following problems:
- It was not possible to know which dependencies required the ``setup.py`` file
to be properly executed.
-- The default Python package installer, `pip`_, expected `setuptools`_ to be the
- default build system tool, excluding others like `flit`_ and `poetry`_.
+- The default Python package installer, `pip`_, expected `Setuptools `_
+ to be the default build system tool, excluding others like `Flit`_ and `Poetry`_.
These problems led to the acceptance of `PEP 517`_ and `PEP 518`_.
PEP 517
-------
-`PEP 517`_ allows Python developers to specify the build backend tool for
+PEP 517 allows Python developers to specify the build backend tool for
generating artifacts. The previous :numref:`build system diag` diagram shows the
most popular backends:
-- `Setuptools`_ , while very popular, lacks the ability to declare build time dependencies
+- Setuptools, while very popular, lacks the ability to declare build-time dependencies
and is difficult to extend.
-- `Flit`_ is a lightweight build system tool for Python.
-- `Poetry`_ focuses on dependency management and environment isolation.
+- Flit is a lightweight build system tool for Python.
+- Poetry focuses on dependency management and environment isolation.
-`PEP 517` introduced the ``build-backend`` key inside the
-``[build-system]`` table in the ``pyproject.toml``.
+PEP 517 introduced the ``build-backend`` key inside the
+``[build-system]`` table in the ``pyproject.toml`` file.
PEP 518
-------
-In addition to the ``setup.py`` file, `PEP 518`_ includes a project file named
+In addition to the ``setup.py`` file, PEP 518 includes a project file named
``pyproject.toml``. The main goal of this file is to specify build time dependencies.
-However, some build system tools like `flit`_ or `poetry`_ are able to specify all
+However, some build system tools like Flit or Poetry are able to specify all
project metadata inside the ``pyproject.toml`` file and eliminate usage of the
``setup.py`` file.
To specify the build time requirements, the ``[build-system]`` table must be
declared in the ``pyproject.toml`` file. Within it, the ``requires`` key is
-assigned to a list of strings, which are the build time
-requirements.
+assigned to a list of strings, which are the build time requirements.
-The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in a
+The combination of PEP 517 and PEP 518 leads to the following syntax in a
``pyproject.toml`` file:
.. code:: toml
@@ -99,9 +98,9 @@ metadata.
Setuptools
----------
-`Setuptools`_ has been a part of the Python ecosystem for a long time. Unless
+Setuptools has been a part of the Python ecosystem for a long time. Unless
you require high control over your project's installation steps, you should use
-`flit`_ or `poetry`_.
+Flit or Poetry.
If you do not need a dynamic installation process, you can consider using a
``setup.cfg`` file. However, the ``setup.py`` file is still required. The ``setup.cfg`` file
@@ -120,8 +119,8 @@ to manage virtual environments on their own. Developers must:
* Create a virtual environment and activate it.
* Install the package in editable mode.
-Flit is the default tool for creating a new ``pyansys`` project when using the
-`ansys-templates tool`_.
+Flit is the default tool for creating a new PyAnsys project when using the
+`Ansys templates `_.
The ``[project]`` section specifies the project's metadata and required
dependencies. For more information, see `flit pyproject.toml
@@ -131,7 +130,7 @@ Poetry
------
Because of its ``poetry.lock`` file, Poetry provides strong dependency pinning. When
-installing a package, poetry creates a virtual environment, thus ensuring an isolated
+installing a package, Poetry creates a virtual environment, thus ensuring an isolated
package development environment.
Nevertheless, it is possible to make Poetry ignore the ``poetry.lock`` file with:
@@ -140,7 +139,7 @@ Nevertheless, it is possible to make Poetry ignore the ``poetry.lock`` file with
poetry config virtualenvs.create false --local
-Using `poetry`_ is popular because it:
+Using Poetry is popular because it:
* Supports pinning dependency versions via a ``poetry.lock`` file that can be
used for testing and CI
@@ -149,15 +148,3 @@ Using `poetry`_ is popular because it:
The ``[tool.poetry]`` section contains metadata and defines project
dependencies. For more information, see `poetry pyproject.toml documentation`_.
-
-.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
-.. _PyPI: https://pypi.org/
-.. _pip:
-.. _flit: https://flit.pypa.io/en/latest/
-.. _poetry: https://python-poetry.org/
-.. _poetry pyproject.toml documentation: https://python-poetry.org/docs/pyproject/
-.. _setuptools: https://pypi.org/project/setuptools/
-.. _setuptools metadata fields: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#declarative-config
-.. _flit pyproject.toml guidelines: https://flit.readthedocs.io/en/latest/pyproject_toml.html
-.. _dependabot: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates
-.. _ansys-templates tool: https://github.com/ansys/ansys-templates
diff --git a/doc/source/packaging/index.rst b/doc/source/packaging/index.rst
index 10032d46f..7342b58a2 100644
--- a/doc/source/packaging/index.rst
+++ b/doc/source/packaging/index.rst
@@ -42,18 +42,3 @@ model and API.
templates
structure
build-systems
-
-.. _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/
-.. _Create a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
diff --git a/doc/source/packaging/structure.rst b/doc/source/packaging/structure.rst
index fa2168c87..87c3950ce 100644
--- a/doc/source/packaging/structure.rst
+++ b/doc/source/packaging/structure.rst
@@ -61,13 +61,13 @@ Python libraries
A Python library is the formal way of distributing Python source code. It allows
for reuse and for specifying Python code dependencies. The guidance presented in this section
-is compliant with the `Python Packaging Authority`_ and PyAnsys recommendations.
+is compliant with the `Python Packaging Authority`_ (PyPA) and PyAnsys recommendations.
.. note::
The best way to keep up to date with Python packaging is to check the `Python
- Packaging User Guide`_, maintained by the `Python Packaging Authority`_ (PyPA).
- PyAnsys guidelines are built on top of PyPA guidelines.
+ Packaging User Guide`_, maintained by the PyPA. PyAnsys guidelines are built
+ on top of the PyPA guidelines.
Scripts, modules, subpackages, and packages
--------------------------------------------
@@ -304,7 +304,7 @@ process but can also introduce security issues.
.. note::
- The ``setup.py`` is only compatible with `setuptools`_. Consider using a
+ The ``setup.py`` file is only compatible with `setuptools`_. Consider using a
``pyproject.toml`` file instead.
While a ``setup.cfg`` file can be used to specify the metadata and packages, the ``setup.py``
@@ -318,23 +318,3 @@ template can be used:
.. include:: code/setup_file_code.rst
-.. REFERENCES & LINKS
-
-.. _MIT License: https://opensource.org/licenses/MIT
-.. _PEP 420: https://peps.python.org/pep-0420/
-.. _native namespace packages: https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages
-.. _Namespace packages: https://packaging.python.org/guides/packaging-namespace-packages/
-.. _PyAnsys: https://docs.pyansys.com/
-.. _Python Packaging User Guide: https://packaging.python.org/en/latest/
-.. _Python Packaging Authority: https://www.pypa.io/en/latest/
-.. _pytest: https://docs.pytest.org/en/latest/
-.. _Sphinx: https://www.sphinx-doc.org/en/master/
-.. _PyMAPDL: https://github.com/ansys/pymapdl
-.. _PyAEDT: https://github.com/ansys/PyAEDT
-.. _ansys-api-mapdl: https://pypi.org/project/ansys-api-mapdl/
-.. _reStructuredText Markup Syntax: https://docutils.sourceforge.io/rst.html
-.. _Markdown Syntax: https://www.markdownguide.org/basic-syntax/
-.. _PEP 518: https://peps.python.org/pep-0518/
-.. _Building and Distributing Packages with Setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
-.. _Configuring setuptools using setup.cfg files: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
-.. _setuptools: https://setuptools.pypa.io/en/latest/index.html
diff --git a/doc/source/packaging/templates.rst b/doc/source/packaging/templates.rst
index 172629f89..46fd969d1 100644
--- a/doc/source/packaging/templates.rst
+++ b/doc/source/packaging/templates.rst
@@ -11,7 +11,7 @@ coding and API style guidelines.
The ``ansys-templates`` tool
============================
-The `ansys-templates`_ tool is a command-ine interface that provides a
+The ``ansys-templates`` tool is a command-ine interface that provides a
collection of templates. When you use this tool to create a PyAnsys project, your
responses to the several questions that are asked result in dynamic project generation.
@@ -35,7 +35,7 @@ projects: ``pyansys`` and ``pyansys-advanced``.
.. important::
- To access these templates, you must install `ansys-templates`_.
+ To access these templates, you must install the ``ansys-templates`` package.
For information on how to use this tool, see `User guide`_ in the
Ansys templates documentation.
@@ -77,12 +77,6 @@ To create a project based on the ``pyansys-advanced`` template, run this code:
ansys-templates new pyansys-advanced
-.. _ansys-templates: https://templates.ansys.com/index.html
.. _Getting started: https://templates.ansys.com/version/stable/getting_started/index.html
.. _User guide: https://templates.ansys.com/version/stable/user_guide/index.html
.. _ansys-templates issues board: https://github.com/ansys/ansys-templates/issues
-.. _flit: https://flit.readthedocs.io/en/latest/
-.. _poetry: https://python-poetry.org/
-.. _pre-commit: https://pre-commit.com/
-.. _setuptools: https://pypi.org/project/setuptools/
-.. _Tox: https://tox.wiki/en/latest/
diff --git a/doc/styles/Vocab/ANSYS/accept.txt b/doc/styles/Vocab/ANSYS/accept.txt
index 73de64d88..fd4f1f8f9 100644
--- a/doc/styles/Vocab/ANSYS/accept.txt
+++ b/doc/styles/Vocab/ANSYS/accept.txt
@@ -26,8 +26,11 @@ Dev
[Dd]ocstring
[Dd]ocstrings
[Dd]octest
+Docutils
dotfiles
dunder
+[Ee]num
+[Ee]nums
Fortran
(?i)Git
[Gg]itHub
@@ -35,6 +38,7 @@ GitHub Actions
[Hh]otfixes
Hpertext
(?i)Html
+imag
initialisms
initializer
internetworking
@@ -42,7 +46,9 @@ internetworking
linenos
matplotlib
Maxime
-MeiliSearchMicroelectromechanical
+MeiliSearch
+metapackage
+Microelectromechanical
monospaced
Muela
[Nn]amespace
@@ -55,13 +61,17 @@ PEP 8
PEP 517
PEP 518
[Pp][Dd][Ff]
+plaintext
pluggable
[Pp]ostprocessing
+(?i)PR
Protobuf
proto
+(?i)PY
(?i)Pyaedt
(?i)Pyansys
Pydocstyle
+Pylance
(?i)Pymapdl
PyMeilisearch
PyPI
@@ -69,6 +79,7 @@ pytest
[Pp]ython
pythoncom
pyvista
+rebasing
reusability
Rey
REST
@@ -78,8 +89,12 @@ scipy
[Ss]etuptools
[Ss]phinx
SSH
-subpackages
+subclassing
+sublist
+[Ss]ubpackage
+[Ss]ubpackages
substring
+superset
tensorflow
TXT
turbomachinery
@@ -87,7 +102,10 @@ UDFs
uncomment
unittest
unvalidated
+URIs
+Vale
venv
+Visual Studio Code
worktree
(?i)WSL
WSL2