[doc] Small improvements to unit testing and precommit sections

.devcontainer/codespaces-docs/welcome.rst

@@ -94,6 +94,17 @@ To stop all webservers use the following command:
 
 For more information, visit `Forwarding ports in your codespace <https://docs.github.com/en/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace>`_.
 
+Issues
+======
+
+For troubleshooting, visit
+`Troubleshooting PyMAPDL <https://mapdl.docs.pyansys.com/version/stable/user_guide/troubleshoot.html#troubleshooting-pymapdl>`_
+
+On the `PyMAPDL Issues <https://github.com/ansys/pymapdl/issues>`_ page,
+you can create issues to report bugs and request new features.
+On the `PyMAPDL Discussions <https://github.com/ansys/pymapdl/discussions>`_ page or
+the `Discussions <https://discuss.ansys.com/>`_ page on the Ansys Developer portal,
+you can post questions, share ideas, and get community feedback. 
 
 😊 Finally
 ==========

.devcontainer/welcome.rst

@@ -42,6 +42,39 @@ which describes the necessary steps.
 You can see the latest documentation on using Codespaces with PyMAPDL in
 `here <https://mapdl.docs.pyansys.com/version/dev/getting_started/devcontainer_link.html>`_.
 
+Testing
+-------
+
+To test new features and check their compatibility with the current library,
+you need to implement unit tests.
+Details on how to implement unit tests can be found in
+`Unit testing <https://mapdl.docs.pyansys.com/version/dev/getting_started/develop_pymapdl.html#unit-testing>`_.
+But remember to use ``xvfb-run`` when you call the ``pytest`` library.
+
+.. code:: console
+
+    (.venv) mapdl@machine:~/pymapdl$ xvfb-run pytest
+    =================================================================== test session starts ====================================================================
+    platform linux -- Python 3.10.12, pytest-7.4.4, pluggy-1.3.0
+    rootdir: /home/mapdl/pymapdl
+    configfile: pyproject.toml
+    ...
+
+For more information visit `Develop code <https://mapdl.docs.pyansys.com/version/dev/getting_started/develop_pymapdl.html#develop-pymapdl>`_.
+
+
+Issues
+======
+
+For troubleshooting, visit
+`Troubleshooting PyMAPDL <https://mapdl.docs.pyansys.com/version/stable/user_guide/troubleshoot.html#troubleshooting-pymapdl>`_
+
+On the `PyMAPDL Issues <https://github.com/ansys/pymapdl/issues>`_ page,
+you can create issues to report bugs and request new features.
+On the `PyMAPDL Discussions <https://github.com/ansys/pymapdl/discussions>`_ page or
+the `Discussions <https://discuss.ansys.com/>`_ page on the Ansys Developer portal,
+you can post questions, share ideas, and get community feedback. 
+
 
 😊 Finally
 ==========

doc/source/getting_started/develop_pymapdl.rst

@@ -134,7 +134,8 @@ Unit testing is highly important. The tests verify that code changes are
 consistent with other parts of the code and verify that these changes are
 implemented properly.
 
-Unit tests are in the `tests <pymapdl_tests_>`_ directory in this repository,
+In the PyMAPDL repository, `pytest <pytest_>`_ is used to run tests and the
+unit tests are in the `tests <pymapdl_tests_>`_ directory in this repository,
 along with integration tests. The difference between a unit test and an
 integration test is that the latter tests several units of the code to ensure
 that they all work together.
@@ -158,7 +159,6 @@ this library:
 
 **Awesome library**
 
-
 .. code:: python
 
     def get_report_colors(theme):
@@ -203,6 +203,27 @@ Or, if a method is a bit more complex, you can split the case in different tests
 While the code coverage in either case is 100% for the function, the second case is
 more useful for debugging the function.
 
+You can also use `parametrize (pytest.mark.parametrize) <pytest_parametrize_>`_ to
+make the code more readable, and easier to reuse.
+
+.. code:: python
+
+    @pytest.mark.parametrize(
+        "theme,output",
+        [
+            ["weather", "traffic", "other"],
+            [
+                ["blue", "lightblue", "grey"]["red", "orange", "yellow"][
+                    "red", "blue", "green"
+                ]
+            ],
+        ],
+    )
+    def test_get_report_color(theme, output):
+        assert get_report_colors(theme) == output
+
+
+For further explanations, see the `pytest documentation <pytest_>`_ .
 
 Continuous integration and continuous deployment
 ------------------------------------------------
@@ -218,8 +239,6 @@ providing a comprehensive CI/CD approach.
 Creation of a unit test
 -----------------------
 
-In the PyMAPDL repository, `pytest <pytest_>`_ is used to run tests. 
-
 The name of a ``pytest`` file must be in the form ``test_XXX.py``, where ``XXX``
 is either the function, method, or class that you are testing or some other explicative
 name. In the command line, you can use the ``-k`` argument to filter the tests to run.
@@ -251,7 +270,6 @@ It is executed upstream of each test and not within all tests.
 
        return True  # if everything goes ok until here
 
-
 If you do not have MAPDL installed locally but still want to run the
 unit testing, you must set up the following environment variables.
 
@@ -282,8 +300,6 @@ multiple versions of MAPDL are installed).
 Example
 --------
 
-.. TO BE MODIFIED
-
 The `test_component.py <pymapdl_test_component_>`_ file contains
 the unit tests and integration tests for the
 :class:`ComponentManager <ansys.mapdl.core.component.ComponentManager>` class.
@@ -321,30 +337,74 @@ Here are some examples of how you use ``pytest``:
 
 For further explanations, see the `pytest documentation <pytest_>`_.
 
-
-
 Code style
 ==========
 
 PyMAPDL follows the PEP8 standard as outlined in the `PyAnsys Development Guide
 <dev_guide_pyansys_>`_ and implements style checking using
 `pre-commit <precommit_>`_.
 
-To ensure your code meets minimum code styling standards, run these commands::
+To ensure your code meets minimum code styling standards, run these commands:
 
-  pip install pre-commit
-  pre-commit run --all-files
+.. code:: console
+
+   (.venv) mapdl@machine:~/pymapdl$ pip install pre-commit
+   (.venv) mapdl@machine:~/pymapdl$ pre-commit run --all-files
+
+You can also install this as a pre-commit hook by running this command:
+
+.. code:: console
 
-You can also install this as a pre-commit hook by running this command::
+    (.venv) mapdl@machine:~/pymapdl$ pre-commit install
 
-  pre-commit install
+Since you have installed ``pre-commit`` as a hook, ``git`` automatically
+runs these hooks before committing, failing if it find any
+format issues and making or proposing the necessary changes
+to the commit.
+If this happens, you might need to run commit and edit these
+changes several times before commit successfully.
 
-This way, it's not possible for you to push code that fails the style checks. For example::
+.. code:: console
+
+   (.venv) mapdl@machine:~/pymapdl$ git commit -m "my commit"
+   [INFO] Stashing unstaged files to /home/mapdl/.cache/pre-commit/patch1704703895-16914.
+   Add License Headers......................................................Passed
+   isort....................................................................Passed
+   numpydoc-validation......................................................Passed
+   black....................................................................Passed
+   blacken-docs.............................................................Failed
+   - hook id: blacken-docs
+   - exit code: 1
+   - files were modified by this hook
+
+   doc/source/getting_started/develop_pymapdl.rst: Rewriting...
 
-  $ pre-commit install
-  $ git commit -am "added my cool feature"
-  black....................................................................Passed
-  isort....................................................................Passed
-  flake8...................................................................Passed
-  codespell................................................................Passed
+This way, it's not possible for you to push code that fails the style checks. For example:
+
+.. code:: console
 
+   (.venv) mapdl@machine:~/pymapdl$ git commit -m "my commit"
+   [WARNING] Unstaged files detected.
+   [INFO] Stashing unstaged files to /home/mapdl/.cache/pre-commit/patch1704703895-16914.
+   Add License Headers..................................(no files to check)Skipped
+   isort................................................(no files to check)Skipped
+   numpydoc-validation..................................(no files to check)Skipped
+   black................................................(no files to check)Skipped
+   blacken-docs.............................................................Passed
+   flake8...............................................(no files to check)Skipped
+   codespell................................................................Passed
+   check for merge conflicts................................................Passed
+   debug statements (python)............................(no files to check)Skipped
+   Validate GitHub Workflows............................(no files to check)Skipped
+   [INFO] Restored changes from /home/mapdl/.cache/pre-commit/patch1704703895-16914.
+   [ci/codespaces-quick-fixes-regarding-welcome-page c0f59f4c] my commit
+   1 file changed, 25 insertions(+)
+   (.venv) mapdl@machine:~/pymapdl$ 
+
+
+First time you run ``pre-commit`` (using ``git commit`` or ``pre-commit``), the command
+might take a bit of time (2-3 minutes) to download the specified hooks and install them.
+After that first time, analysing your commits should take seconds.
+
+``pre-commit`` hooks can also be updated, added or removed. For more information, visit
+`pre-commit <precommit_>`_ website.

doc/source/links.rst

@@ -121,7 +121,7 @@
 .. _vscode_devcontainers_remote_extension: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack
 .. _ghcr: https://github.com/features/packages
 .. _vscode_open_a_repository_in_container: https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume
-
+.. _pytest_parametrize: https://docs.pytest.org/en/7.3.x/how-to/parametrize.html
 
 
 .. #Github links: