From 701a234b55fd1b0602bcfd9af54a9417e3435660 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 8 Jan 2024 08:44:06 +0000 Subject: [PATCH 1/4] Improving welcome page --- .devcontainer/codespaces-docs/welcome.rst | 11 ++++++++ .devcontainer/welcome.rst | 33 +++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/.devcontainer/codespaces-docs/welcome.rst b/.devcontainer/codespaces-docs/welcome.rst index cdc55291fb..67272b4dae 100644 --- a/.devcontainer/codespaces-docs/welcome.rst +++ b/.devcontainer/codespaces-docs/welcome.rst @@ -91,6 +91,17 @@ To stop all webservers use the following command: For more information, visit `Forwarding ports in your codespace `_. +Issues +====== + +For troubleshooting, visit +`Troubleshooting PyMAPDL `_ + +On the `PyMAPDL Issues `_ page, +you can create issues to report bugs and request new features. +On the `PyMAPDL Discussions `_ page or +the `Discussions `_ page on the Ansys Developer portal, +you can post questions, share ideas, and get community feedback. 😊 Finally ========== diff --git a/.devcontainer/welcome.rst b/.devcontainer/welcome.rst index 5515d66822..94e324b354 100644 --- a/.devcontainer/welcome.rst +++ b/.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 `_. +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 `_. +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 `_. + + +Issues +====== + +For troubleshooting, visit +`Troubleshooting PyMAPDL `_ + +On the `PyMAPDL Issues `_ page, +you can create issues to report bugs and request new features. +On the `PyMAPDL Discussions `_ page or +the `Discussions `_ page on the Ansys Developer portal, +you can post questions, share ideas, and get community feedback. + 😊 Finally ========== From bf5570357ba826b459900cbfd047ac210c494b47 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 8 Jan 2024 09:04:20 +0000 Subject: [PATCH 2/4] Improving testing and precommit sections --- .../getting_started/develop_pymapdl.rst | 91 ++++++++++++++++--- doc/source/links.rst | 2 +- 2 files changed, 78 insertions(+), 15 deletions(-) diff --git a/doc/source/getting_started/develop_pymapdl.rst b/doc/source/getting_started/develop_pymapdl.rst index 9132f8e90f..b643f1604f 100644 --- a/doc/source/getting_started/develop_pymapdl.rst +++ b/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 `_ directory in this repository, +In the PyMAPDL repository, `pytest `_ is used to run tests and the +unit tests are in the `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. @@ -203,6 +204,25 @@ 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 make the code more readable, and easiert to reuse by using +`parametrize (pytest.mark.parametrize) `_. + +.. 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 + Continuous integration and continuous deployment ------------------------------------------------ @@ -218,8 +238,6 @@ providing a comprehensive CI/CD approach. Creation of a unit test ----------------------- -In the PyMAPDL repository, `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. @@ -322,7 +340,6 @@ Here are some examples of how you use ``pytest``: For further explanations, see the `pytest documentation `_. - Code style ========== @@ -332,19 +349,65 @@ PyMAPDL follows the PEP8 standard as outlined in the `PyAnsys Development Guide 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:: - pre-commit install +.. code:: console -This way, it's not possible for you to push code that fails the style checks. For example:: + (.venv) mapdl@machine:~/pymapdl$ 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. + +.. 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 - $ pre-commit install - $ git commit -am "added my cool feature" - black....................................................................Passed - isort....................................................................Passed - flake8...................................................................Passed - codespell................................................................Passed + doc/source/getting_started/develop_pymapdl.rst: Rewriting... + +This way, it's not possible for you to push code that fails the style checks. For example:: +.. code:: + + (.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 `_ website. \ No newline at end of file diff --git a/doc/source/links.rst b/doc/source/links.rst index 9fa9f1f77d..c635e619b7 100644 --- a/doc/source/links.rst +++ b/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: From f280ed1eb0b8a8e21efe20577fe6edbc7753dcd0 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 8 Jan 2024 09:14:24 +0000 Subject: [PATCH 3/4] fixing vale issues --- .../getting_started/develop_pymapdl.rst | 72 +++++++++---------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/doc/source/getting_started/develop_pymapdl.rst b/doc/source/getting_started/develop_pymapdl.rst index b643f1604f..ae196da461 100644 --- a/doc/source/getting_started/develop_pymapdl.rst +++ b/doc/source/getting_started/develop_pymapdl.rst @@ -204,8 +204,8 @@ 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 make the code more readable, and easiert to reuse by using -`parametrize (pytest.mark.parametrize) `_. +You can also use `parametrize (pytest.mark.parametrize) `_ to +make the code more readable, and easier to reuse. .. code:: python @@ -224,6 +224,8 @@ You can also make the code more readable, and easiert to reuse by using assert get_report_colors(theme) == output +For further explanations, see the `pytest documentation `_. + Continuous integration and continuous deployment ------------------------------------------------ @@ -300,8 +302,6 @@ multiple versions of MAPDL are installed). Example -------- -.. TO BE MODIFIED - The `test_component.py `_ file contains the unit tests and integration tests for the :class:`ComponentManager ` class. @@ -351,8 +351,8 @@ To ensure your code meets minimum code styling standards, run these commands:: .. code:: console - (.venv) mapdl@machine:~/pymapdl$ pip install pre-commit - (.venv) mapdl@machine:~/pymapdl$ pre-commit run --all-files + (.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:: @@ -369,40 +369,40 @@ changes several times before commit successfully. .. 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 + (.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... + doc/source/getting_started/develop_pymapdl.rst: Rewriting... This way, it's not possible for you to push code that fails the style checks. For example:: -.. code:: - - (.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$ +.. 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 From 1860f2a7122fe2222a7d76e323cb4f254c850753 Mon Sep 17 00:00:00 2001 From: German Date: Mon, 8 Jan 2024 10:27:37 +0100 Subject: [PATCH 4/4] fixing vale --- doc/source/getting_started/develop_pymapdl.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/doc/source/getting_started/develop_pymapdl.rst b/doc/source/getting_started/develop_pymapdl.rst index ae196da461..7572582462 100644 --- a/doc/source/getting_started/develop_pymapdl.rst +++ b/doc/source/getting_started/develop_pymapdl.rst @@ -159,7 +159,6 @@ this library: **Awesome library** - .. code:: python def get_report_colors(theme): @@ -224,7 +223,7 @@ make the code more readable, and easier to reuse. assert get_report_colors(theme) == output -For further explanations, see the `pytest documentation `_. +For further explanations, see the `pytest documentation `_ . Continuous integration and continuous deployment ------------------------------------------------ @@ -271,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. @@ -339,7 +337,6 @@ Here are some examples of how you use ``pytest``: For further explanations, see the `pytest documentation `_. - Code style ========== @@ -347,14 +344,14 @@ PyMAPDL follows the PEP8 standard as outlined in the `PyAnsys Development Guide `_ and implements style checking using `pre-commit `_. -To ensure your code meets minimum code styling standards, run these commands:: +To ensure your code meets minimum code styling standards, run these commands: .. 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:: +You can also install this as a pre-commit hook by running this command: .. code:: console @@ -382,7 +379,7 @@ changes several times before commit successfully. doc/source/getting_started/develop_pymapdl.rst: Rewriting... -This way, it's not possible for you to push code that fails the style checks. For example:: +This way, it's not possible for you to push code that fails the style checks. For example: .. code:: console