DOCS: Refactor

README.rst

@@ -49,7 +49,7 @@ Mechanical within Python's ecosystem. It includes the ability to:
 Install the package
 -------------------
 
-Install PyMechanical using `pip` with::
+Install PyMechanical using ``pip`` with::
 
    pip install ansys-mechanical-core
 

doc/changelog.d/878.documentation.md

@@ -0,0 +1 @@
+Refactor

doc/source/conf.py

@@ -233,6 +233,9 @@
     "examples/index": [],
     "contributing": [],
 }
+
+html_show_sourcelink = False
+
 # -- Options for LaTeX output ------------------------------------------------
 latex_elements = {}
 
@@ -305,6 +308,7 @@
     "https://download.ansys.com/*",
     "https://support.ansys.com/*",
     "https://discuss.ansys.com/*",
+    "https://www.ansys.com/*",
     "../api/*",  # Remove this after release 0.10.12
     "path.html",
 ]

doc/source/contributing.rst

@@ -10,94 +10,86 @@ with this guide before attempting to contribute to PyMechanical.
 
 The following contribution information is specific to PyMechanical.
 
-Install in developer mode
--------------------------
+Clone the repository and install project dependencies
+-----------------------------------------------------
 
-Installing PyMechanical in developer mode allows
-you to modify the source and enhance it.
+To clone and install the latest PyMechanical release in development mode, run
+these commands:
 
-.. note::
-
-    Before contributing to the project, ensure that you are thoroughly familiar
-    with the `PyAnsys Developer's Guide`_.
-
-To install PyMechanical in developer mode, perform these steps:
-
-#. Clone the ``pymechanical`` repository:
-
-   .. code:: bash
-
-      git clone https://github.com/ansys/pymechanical
-
-#. Access the ``pymechanical`` directory where the repository has been cloned:
-
-   .. code:: bash
-
-      cd pymechanical
-
-#. Create a clean Python virtual environment and activate it:
-
-.. tab-set::
-
-    .. tab-item:: Windows
-
-        .. tab-set::
+.. code::
 
-            .. tab-item:: CMD
+    # Clone the repository
+    git clone https://github.com/ansys/pymechanical
+    cd pymechanical
 
-                .. code-block:: text
+    # Create a virtual environment
+    python -m venv .venv
 
-                    python -m venv .venv
-                    .venv\Scripts\activate.bat
+    # Activate the virtual environment depending on the operating system
+    # Windows
+    .venv\Scripts\activate.bat
 
-            .. tab-item:: PowerShell
+    # PowerShell
+    .venv\Scripts\Activate.ps1
 
-                .. code-block:: text
+    # Linux/UNIX
+    source .venv/bin/activate
 
-                    python -m venv .venv
-                    .venv\Scripts\Activate.ps1
+    # Install build system tools
+    python -m pip install --upgrade pip tox flit twine
 
-    .. tab-item:: Linux/UNIX
+    # Install the project in editable mode using one of the following commands:
+    # Install the project dependencies only
+    python -m pip install -e .
 
-        .. code-block:: text
+    # Install the project and test dependencies
+    python -m pip install -e .[tests]
 
-            python -m venv .venv
-            source .venv/bin/activate
+    # Install the project and documentation dependencies
+    python -m pip install -e .[doc]
 
+    # Install the project, test, and documentation dependencies
+    python -m pip install -e .[tests,doc]
 
-#. Ensure that you have the latest required build system tools:
+Test PyMechanical
+-----------------
 
-   .. code:: bash
+PyMechanical uses `PyTest`_ and `tox`_ for unit testing. Prior to running the tests,
+ensure Mechanical is installed on your system with a valid license and the test
+dependencies are installed. Run this command to install the test dependencies::
 
-      python -m pip install -U pip tox flit twine
+  pip install -e .[tests]
 
-#. Install the project in editable mode:
+Using ``pytest``
+^^^^^^^^^^^^^^^^
 
-   .. code:: bash
+To run the tests, navigate to the root directory of the repository and run this command::
 
-      # Install the minimum requirements
-      python -m pip install -e .
+    pytest
 
-      # Install the minimum + tests requirements
-      python -m pip install -e .[tests]
+The ``pytest`` command runs all of the tests in the ``tests`` folder. After ``pytest`` is
+done running, it shows the test coverage of each of the files in the repository. To run
+specific tests, run these commands::
 
-      # Install the minimum + doc requirements
-      python -m pip install -e .[doc]
+    # Run tests for embedded instances
+    pytest -m embedding
 
-      # Install all requirements
-      python -m pip install -e .[tests,doc]
+    # Run tests for embedded instances that use subprocess
+    pytest -m embedding_scripts
 
-#. Verify your development installation:
+    # Run tests that launch Mechanical and work with the gRPC server inside of it
+    pytest -m remote_session_launch
 
-    .. code:: bash
+    # Run tests that connect to Mechanical and work with the gRPC server inside of it
+    pytest -m remote_session_connect
 
-        tox
+See the ``pyproject.toml`` file for a full list of markers (-m) and their descriptions.
 
+To run specific tests based on a keyword, use the ``-k`` argument::
 
-Test PyMechanical
------------------
-
-PyMechanical uses `PyTest`_ and `tox`_ for unit testing.
+    # Run all tests containing the word ``appdata``
+    # This would run ``test_private_appdata`` and ``test_normal_appdata`` only
+    pytest -k appdata
 
 Using ``tox``
 ^^^^^^^^^^^^^
@@ -116,14 +108,6 @@ The following environment commands are provided:
 - ``tox -e py-coverage``: Checks for unit testing and code coverage.
 - ``tox -e doc``: Checks for documentation-building process.
 
-Without ``tox``
-^^^^^^^^^^^^^^^
-
-If required, from the command line, you can call style commands like
-`black`_, `isort`_, and `flake8`_. You can also call unit testing commands like `PyTest`_.
-However, running these commands do not guarantee that your project is being tested
-in an isolated environment, which is the reason why tools like ``tox`` exist.
-
 Remote testing
 ^^^^^^^^^^^^^^
 If you do not have a licensed copy of Mechanical installed locally but want to
@@ -151,20 +135,45 @@ to attempt to connect to the existing Mechanical service by default
 when you use the :func:`launch_mechanical() <ansys.mechanical.core.launch_mechanical>`
 method.
 
+Adhere to coding style
+----------------------
+
+As indicated in `Coding style <https://dev.docs.pyansys.com/coding-style/index.html>`_
+in the *PyAnsys Developer's Guide*, PyMechanical follows PEP8 guidelines. PyMechanical
+implements `pre-commit <https://pre-commit.com/>`_ for style checking.
+
+To ensure your code meets minimum code styling standards, run these commands::
+
+  pip install pre-commit
+  pre-commit run --all-files
+
+You can also install this as a pre-commit hook by running this command::
+
+  pre-commit install
+
+This way, it's not possible for you to push code that fails the style checks::
+
+  $ pre-commit install
+  $ git commit -am "added my cool feature"
+  black....................................................................Passed
+  isort....................................................................Passed
+  flake8...................................................................Passed
+  codespell................................................................Passed
+
 Documentation
 -------------
 
 For building documentation, you can run the usual rules provided in the
-`Sphinx`_ ``make`` file. Here is an example:
+`Sphinx`_ ``make`` file:
 
 .. code:: bash
 
     #  build and view the doc from the POSIX system
-    make -C doc/ html && your_browser_name doc/html/index.html
+    make -C doc html && your_browser_name doc/html/index.html
 
     # build and view the doc from a Windows environment
-    .\doc\make.bat clean
-    .\doc\make.bat html
+    make -C doc clean
+    make -C doc html
     start .\doc\_build\html\index.html
 
 However, the recommended way of checking documentation integrity is to use
@@ -174,32 +183,6 @@ However, the recommended way of checking documentation integrity is to use
 
     tox -e doc && your_browser_name .tox/doc_out/index.html
 
-Distributing
-------------
-
-If you would like to create either source or wheel files, start by installing
-the building requirements and then executing the build module:
-
-.. code:: bash
-
-    python -m pip install -U pip
-    python -m flit build
-    python -m twine check dist/*
-
-Post issues
------------
-
-Use the `PyMechanical Issues <https://github.com/ansys/pymechanical/issues>`_
-page to submit questions, report bugs, and request new features. When possible,
-use these templates:
-
-* Bug report
-* Feature request
-
-If your issue does not fit into one of these template categories, create your own issue.
-
-To reach the project support team, email `[email protected] <[email protected]>`_.
-
 View documentation
 ------------------
 
@@ -211,30 +194,17 @@ for switching from viewing the documentation for the latest stable release
 to viewing the documentation for the development version or previously
 released versions.
 
-Code style
-----------
-
-As indicated in `Coding style <https://dev.docs.pyansys.com/coding-style/index.html>`_
-in the *PyAnsys Developer's Guide*, PyMechanical follows PEP8 guidelines. PyMechanical
-implements `pre-commit <https://pre-commit.com/>`_ for style checking.
-
-To ensure your code meets minimum code styling standards, run these commands::
-
-  pip install pre-commit
-  pre-commit run --all-files
-
-You can also install this as a pre-commit hook by running this command::
+Post issues
+-----------
 
-  pre-commit install
+Use the `PyMechanical Issues <https://github.com/ansys/pymechanical/issues>`_
+page to submit questions, report bugs, and request new features. When possible,
+use these templates:
 
-This way, it's not possible for you to push code that fails the style checks::
+* Bug report
+* Feature request
 
-  $ pre-commit install
-  $ git commit -am "added my cool feature"
-  black....................................................................Passed
-  isort....................................................................Passed
-  flake8...................................................................Passed
-  codespell................................................................Passed
+If your issue does not fit into one of these template categories, create your own issue.
 
 .. LINKS AND REFERENCES
 .. _PyAnsys Developer's Guide: https://dev.docs.pyansys.com/

doc/source/examples/index.rst

@@ -6,28 +6,28 @@ Examples
 Here are examples using Mechanical with the ``ansys-mechanical-core`` library through
 an embedded instance or remote session.
 
-.. grid:: 2
+.. grid:: 1 2 2 2
 
    .. grid-item-card:: Embedding Examples
-      :link: https://embedding.examples.mechanical.docs.pyansys.com/index.html
+      :padding: 2 2 2 2
+      :link: https://embedding.examples.mechanical.docs.pyansys.com/examples/index.html
       :text-align: center
-      :margin: 2 2 0 0
 
       Uses PyMechanical to embed an instance of Mechanical directly within Python as a Python object.
 
    .. grid-item-card:: Remote Session Examples
-      :link: https://examples.mechanical.docs.pyansys.com/index.html
+      :padding: 2 2 2 2
+      :link: https://examples.mechanical.docs.pyansys.com/examples/index.html
       :text-align: center
-      :margin: 2 2 0 0
 
       Uses PyMechanical as a client to a remote Mechanical instance.
 
 .. grid:: 1
 
    .. grid-item-card:: Embedding Instance & Remote Session Example
+      :padding: 2 2 2 2
       :link: gallery_examples/embedding_n_remote/embedding_remote.html
       :text-align: center
-      :margin: 2 2 0 0
 
       Demonstrates the same model setup in both an embedded instance and remote session,
       as well as examples using a combination of embedded instances and remote sessions.