From e1034f32584eaed2c9059584be9aa71704f5206d Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 21 Nov 2023 12:22:11 +0100 Subject: [PATCH] API and contribution sections small reorganization (#2491) * API reog. Extended documentation about writing example and developing PyMAPDL. * Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update doc/source/getting_started/develop_pymapdl.rst * Update doc/source/links.rst * Simplifying accept file * fixing title --------- Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- doc/source/api/building_example.rst | 92 ----- doc/source/api/index.rst | 2 - doc/source/api/unit_testing.rst | 174 --------- doc/source/getting_started/contribution.rst | 142 +++----- .../getting_started/develop_pymapdl.rst | 335 ++++++++++++++++++ .../getting_started/write_documentation.rst | 232 ++++++++++++ doc/source/links.rst | 10 + doc/source/user_guide/troubleshoot.rst | 3 +- doc/styles/Vocab/ANSYS/accept.txt | 13 +- 9 files changed, 637 insertions(+), 366 deletions(-) delete mode 100644 doc/source/api/building_example.rst delete mode 100644 doc/source/api/unit_testing.rst create mode 100644 doc/source/getting_started/develop_pymapdl.rst create mode 100644 doc/source/getting_started/write_documentation.rst diff --git a/doc/source/api/building_example.rst b/doc/source/api/building_example.rst deleted file mode 100644 index ee5d1f9a04..0000000000 --- a/doc/source/api/building_example.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _ref_building_example: - - -=================== -Building an example -=================== - -.. currentmodule:: ansys.mapdl.core.building_example - -To run the documentation, you need to have the correct versions of each tool. To do so, execute the -following instruction. - -.. code:: console - - pip install -r requirements/requirements_docs.txt - - -The Sphinx configuration is in the file -`conf.py `_ in :file:`doc/source`. - - -To run the sphinx tool: - -.. code:: pwsh-session - - doc\make.bat html - - -There are three types of examples: dynamic, static, and semi-static. - -* `Dynamic examples`_ -* `Static examples`_ -* `Semi-dynamic examples`_ - - -Dynamic examples ----------------- - -The dynamic examples are based on Python files and must be able to run in under three minutes. - -They are in the `examples `_ directory in this repository. - -.. vale off - -Example: `2d_plate_with_a_hole.py `_ -.. vale on - -Here is a link to this dynamic example: -`MAPDL 2D Plane Stress Concentration Analysis `_ - -When an example is executed, **Total running time of the script** appears at the end of -the document. - - -Static examples ---------------- - -Static examples are based on RST files and are not executed. - -They are in the `doc\source `_ directory. -.. vale off - -Example: `krylov_example.rst `_ -.. vale on - -Here is a link to this static example: `Harmonic analysis using the frequency-sweep Krylov method `_ - - -Semi-dynamic examples ---------------------- - -Semi-dynamic examples are RST files that execute Python code using this RST directive: - -.. code:: rst - - .. jupyter-execute:: - :hide-code: - - -.. vale off - -Example: `tecfricstir.rst `_ -.. vale on - -Here is a link to this semi-dynamic example: `Friction Stir Welding (FSW) Simulation `_ - - -Recommendations ---------------- - -As dynamic examples must run each time documentation is built, make sure that they are very short. -To get around the problem of execution time, feel free to use static or semi-static examples. diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index e452fe45ff..459792ce43 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -36,5 +36,3 @@ PyMAPDL, see :ref:`ref_mapdl_commands`. Pyansys Math solution xpl - building_example - unit_testing diff --git a/doc/source/api/unit_testing.rst b/doc/source/api/unit_testing.rst deleted file mode 100644 index 74ac56865b..0000000000 --- a/doc/source/api/unit_testing.rst +++ /dev/null @@ -1,174 +0,0 @@ -.. _ref_unit_testing_contributing: - -Unit testing -============ - -Unit tests validate the software by testing that the logic -implemented inside a certain method, class, or module is -working as expected. They should be as atomic and -independent as possible. - -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, -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. - -To verify that all code is properly tested, you must ensure that every piece -of code is used (covered) in at least one unit test. In this repository, the -`Codecov `_ tool generates a coverage report of the -committed code. It details how merging a pull request would impact coverage. It -is one of the checks that must run successfully to merge code changes. - - -.. figure:: ../images/codecov_increase.png - :width: 400pt - - -Coverage example ----------------- - -To show how the coverage works, assume that you have -this library: - -**Awesome library** - - -.. code:: python - - def get_report_colors(theme): - if theme == "weather": - colors = ["blue", "lightblue", "grey"] - elif theme == "traffic": - colors = ["red", "orange", "yellow"] - else: - colors = ["red", "blue", "green"] - - return colors - - -**Tests** - -You can opt to run the tests with this configuration: - -.. code:: python - - def test_get_report_colors(): - assert get_report_colors("weather") == ["blue", "lightblue", "grey"] - assert get_report_colors("traffic") == ["red", "orange", "yellow"] - assert get_report_colors("other") == ["red", "blue", "green"] - - -Or, if a method is a bit more complex, you can split the case in different tests: - -.. code:: python - - def test_get_report_colors_weather(): - assert get_report_colors("weather") == ["blue", "lightblue", "grey"] - - - def test_get_report_colors_traffic(): - assert get_report_colors("traffic") == ["red", "orange", "yellow"] - - - def test_get_report_colors_other(): - assert get_report_colors("other") == ["red", "blue", "green"] - - -While the code coverage in either case is 100% for the function, the second case is -more useful for debugging the function. - - -Continuous Integration and Continuous Deployment (CI/CD) approach ------------------------------------------------------------------ - -Unit tests and integration tests are part of Continuous Integration (CI). -The automation of testing, monitoring, and deployment of newly added -code allows Continuous Deployment (CD) throughout the app lifecycle, -providing a comprehensive CI/CD approach. - -.. figure:: ../images/cicd.jpg - :width: 300pt - -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, the ``-k`` argument can be used to filter the tests to run. -For more information, see `pytest usage `_. - -Here are some guidelines for creating good unit tests: - -- Assign long and descriptive names to tests. -- Use the `Codecov `_ tool to ensure all implemented code is tested. -- Check that tests return the same results each time. -- Verify that tests are independent. -- Write tests that verify only one part of the code at a time. -- Make tests as short and fast as possible. - -`What makes a good unit test `_ -is an exhaustive list of tips for creating good unit tests. - -Most PyMAPDL tests require a connection to a running instance of -MAPDL, which makes them integration tests. If your test -requires a running MAPDL instance, you can use the PyMAPDL -`mapdl `_ method in your function signature. -It is executed upstream of each test and not within all tests. - -.. code:: python - - def test_my_new_feature(mapdl): # pass the 'mapdl' fixture as an argument. - mapdl.prep7() - # .... more code - - return True # if everything goes ok until here - - -Example --------- - -.. TO BE MODIFIED - -The `test_component.py `_ file contains -the unit tests and integration tests of the -:class:`ComponentManager `. -These are just some of the many tests that you can find in the -`test directory `_. - -Here are some examples of how you use ``pytest``: - -.. code:: python - - import pytest - - - # 'cube_geom_and_mesh' is another fixture defined in 'conftest.py' - @pytest.fixture(scope="function") - def basic_components(mapdl, cube_geom_and_mesh): - """Given a model in 'cube_geom_and_mesh', let's define some components to work with later.""" - mapdl.components["mycomp1"] = "NODE", [1, 2, 3] - mapdl.components["mycomp2"] = "KP", [1, 3] - - mapdl.cmsel("s", "mycomp1") - mapdl.cmsel("a", "mycomp2") - - - def test_dunder_methods_keys(mapdl, basic_components): - assert ["MYCOMP1", "MYCOMP2"] == list(mapdl.components.names()) - - - def test_dunder_methods_types(mapdl, basic_components): - assert ["NODE", "KP"] == list(mapdl.components.types()) - - - def test_dunder_methods_items(mapdl, basic_components): - assert [("MYCOMP1", "NODE"), ("MYCOMP2", "KP")] == list(mapdl.components.items()) - - -For further explanations, see the `pytest documentation `_. \ No newline at end of file diff --git a/doc/source/getting_started/contribution.rst b/doc/source/getting_started/contribution.rst index 8c2662d325..4ed5b5b194 100644 --- a/doc/source/getting_started/contribution.rst +++ b/doc/source/getting_started/contribution.rst @@ -4,106 +4,70 @@ Contributing ============ -Overall guidance on contributing to a PyAnsys library appears in the -`Contributing `_ topic -in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar -with it and all `Coding style `_ before attempting to -contribute to PyMAPDL. - -The following contribution information is specific to PyMAPDL. +.. toctree:: + :hidden: + :maxdepth: 3 -Cloning the PyMAPDL repository -============================== + write_documentation + develop_pymapdl -Run this code to clone and install the latest version of PyMAPDL in development mode: -.. code:: console +There are several ways to contribute to PyMAPDL. - git clone https://github.com/ansys/pymapdl - cd pymapdl - pip install pip -U - pip install -e . +* `Answer discussions`_ +* `Post issues`_ +* :ref:`write_documentation` +* :ref:`developing_pymapdl` +Overall guidance on contributing to a PyAnsys library appears in the +`Contributing `_ topic +in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar +with it and the `Coding style `_ before attempting to +contribute to PyMAPDL. + -Posting issues -============== - -Use the `PyMAPDL Issues `_ -page to submit questions, report bugs, and request new features. When possible, -use these issue templates: +Answer discussions +================== + +Answering discussions is an excellent way to contribute to PyMAPDL, and +it does not require any setup, just a GitHub account. +It is probably the first step towards becoming a full PyMAPDL developer, since it +helps you deepen your understanding of the project. Engaging in +discussions often requires a thorough grasp of the project's goals and +challenges. +Your contributions can help other users or contributors who +may be facing similar issues, making the repository more welcoming and +inclusive. By providing answers or solutions, you can directly contribute to the project's +success, maintain its health, and encourage a positive, open source ecosystem. + +To discover how you can help, see the `PyMAPDL Discussions `_ page. + + +Post issues +=========== + +Posting issues in a repository is a valuable contribution that benefits you, the +repository, and PyMAPDL as a whole. It allows you to voice concerns, suggest +improvements, or report bugs, which can lead to a more robust and user-friendly +project. It also offers an opportunity for you to engage with the project's +community, learn from others, and gain experience in issue tracking and +collaboration. +For the repository, issues serve as a structured way to track and +prioritize work, helping maintainers understand the needs of users and guide the +project's development. It's an excellent way to contribute because it enhances +the project's quality, fosters transparency, and encourages the collective +effort of the community to continuously improve and innovate. + +Use the `PyMAPDL Issues `_ page to submit questions, report bugs, +and request new features. +When possible, use these issue templates: * **🐞 Bug, problem, or error**: Fill a bug report here * **📖 Documentation issue**: Modifications to the documentation only * **🎓 Adding an example**: Proposing a new example for the library * **💡 New feature**: Enhancements to the code -If your issue does not fit into one of these categories, click in `Open a blank issue `_. - - -Viewing PyMAPDL documentation -============================= - -Documentation for the latest stable release of PyMAPDL is hosted at -`PyMAPDL Documentation `_. - -In the upper right corner of the documentation's title bar, there is an option -for switching from viewing the documentation for the latest stable release -to viewing the documentation for the development version or previously -released versions. - -Testing MAPDL -============= - -If you do not have MAPDL installed locally but still want to run the -unit testing, you must set up the following environment variables. - -**On Windows** - -.. code:: pwsh-session - - SET PYMAPDL_START_INSTANCE=False - SET PYMAPDL_PORT= (default 50052) - SET PYMAPDL_IP= (default 127.0.0.1) - -**On Linux** - -.. code:: console - - export PYMAPDL_START_INSTANCE=False - export PYMAPDL_PORT= (default 50052) - export PYMAPDL_IP= (default 127.0.0.1) - -This tells ``ansys.mapdl.core`` to attempt to connect to the existing -MAPDL service by default when the ``launch_mapdl`` function is used. - -Additionally you can use the environment variables ``PYMAPDL_MAPDL_EXEC`` -and ``PYMAPDL_MAPDL_VERSION`` to specify MAPDL executable path and the -version to launch (if multiple versions of MAPDL are installed). - - -Code style -========== - -PyMAPDL follows 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:: - - pip install pre-commit - pre-commit run --all-files - -You can also install this as a pre-commit hook by running:: - - pre-commit install - -This way, it's not possible for you to push code that fails the style checks. For example:: - - $ 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 categories, click +`Open a blank issue `_. \ No newline at end of file diff --git a/doc/source/getting_started/develop_pymapdl.rst b/doc/source/getting_started/develop_pymapdl.rst new file mode 100644 index 0000000000..0d4c19c507 --- /dev/null +++ b/doc/source/getting_started/develop_pymapdl.rst @@ -0,0 +1,335 @@ + +.. _developing_pymapdl: + +============ +Develop code +============ + +You can help improve PyMAPDL by fixing a bug or developing a new feature. +To do either, you must set up the repository on your local machine as per the +explanations in the following sections. + + +Clone the PyMAPDL repository +============================ + +Before cloning the PyMAPDL repository, you must install a version control system such as Git. +You can this run this code to clone the latest development version of PyMAPDL: + +.. code:: console + + git clone https://github.com/ansys/pymapdl + cd pymapdl + + + +Create a Python virtual environment +=================================== + +To avoid dependency conflicts and more easily manage upgrades, you should install PyMAPDL in its own virtual environment. For detailed information on how to install Python and create a virtual environment, see +`Setting up your development environment `_. + +Install PyMAPDL in development mode +=================================== + +Install the latest version of PyMAPDL in development mode with these commands: + + +.. code:: console + + cd pymapdl + pip install pip -U + pip install -e . + + +If you are going to do testing, you must install the testing dependencies with this command: + + +.. code:: console + + pip install -e '.[tests]' + + +Develop PyMAPDL +=============== + +.. epigraph:: *Now it is time to develop PyMAPDL!* + +Developing code in a repository, particularly when using version control systems +like Git, involves a set of essential guidelines to ensure efficient +collaboration, code management, and tracking changes. Here are the main +guidelines for developing code in a repository: + +#. **Use branches**: Create branches for different features, bug fixes, or + experiments. This keeps changes isolated and facilitates parallel + development. + +#. **Write descriptive commit messages**: Provide clear and concise commit + messages that explain the purpose and context of the changes. Follow a + consistent style. + +#. **Commit frequently**: Make small, meaningful commits frequently. Avoid + making a large number of unrelated changes in a single commit. + +#. **Pull before you push**: Always update your local branch with the latest + changes from the remote repository before pushing your own changes to avoid + conflicts. + +#. **Use pull requests (PRs)**: Use PRs to submit your changes for review. + This allows for discussion and validation before merging into the main branch. + +#. **Write good documentation**: Maintain clear and up-to-date documentation for your + contribution or changes, including comments in code, and relevant project + documentation in rST or Markdown files. + If you implement a new feature or change the behaviour of the library in any way, + remember to mention it somewhere in the documentation (rST files in :file:`doc\source` directory) + Follow the `numpydoc `_ convention for documenting code. + +#. **Test your changes**: Thoroughly test your changes to ensure that they work + as expected. If applicable, create or update the unit tests that run on the + continuous integration/continuous deployment (CI/CD) pipelines to catch issues early + and ensure reliable deployments. For more information, see `Unit testing`_. + +#. **Respect code style and standards**: Follow code style + guidelines and adhere to coding standards specific to your language or + framework. + +#. **Collaborate and communicate**: Communicate with team members, provide + updates on your progress, and resolve any conflicts promptly. + +#. **Ask for help**: To ensure code quality, identify issues, and share knowledge, + ask PyMAPDL developers to assist you and review your code. + If you need help or guidance, mention ``@ansys/pymapdl-maintainers`` in a comment + so they they are notified. + +By following these guidelines, you can ensure smooth and organized code +development within a repository, fostering collaboration, code quality, and feature enhancement. + + +.. _ref_unit_testing_contributing: + +Unit testing +============ + +Unit tests validate the software by testing that the logic implemented inside a +certain method, class, or module is working as expected. They should be as +atomic and independent as possible. + +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, +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. + +To verify that all code is properly tested, you must ensure that every piece of +code is used (covered) in at least one unit test. In this repository, the +`Codecov `_ tool generates a coverage report of the committed code. It +indicates how merging a pull request would impact coverage. The generation of this report is one of the +checks that must run successfully to merge code changes. + + +.. figure:: ../images/codecov_increase.png + :width: 400pt + + +Coverage example +---------------- + +To show how the coverage works, assume that you have +this library: + +**Awesome library** + + +.. code:: python + + def get_report_colors(theme): + if theme == "weather": + colors = ["blue", "lightblue", "grey"] + elif theme == "traffic": + colors = ["red", "orange", "yellow"] + else: + colors = ["red", "blue", "green"] + + return colors + + +**Tests** + +You can opt to run the tests with this configuration: + +.. code:: python + + def test_get_report_colors(): + assert get_report_colors("weather") == ["blue", "lightblue", "grey"] + assert get_report_colors("traffic") == ["red", "orange", "yellow"] + assert get_report_colors("other") == ["red", "blue", "green"] + + +Or, if a method is a bit more complex, you can split the case in different tests: + +.. code:: python + + def test_get_report_colors_weather(): + assert get_report_colors("weather") == ["blue", "lightblue", "grey"] + + + def test_get_report_colors_traffic(): + assert get_report_colors("traffic") == ["red", "orange", "yellow"] + + + def test_get_report_colors_other(): + assert get_report_colors("other") == ["red", "blue", "green"] + + +While the code coverage in either case is 100% for the function, the second case is +more useful for debugging the function. + + +Continuous integration and continuous deployment +------------------------------------------------ + +Unit tests and integration tests are part of continuous integration (CI). +The automation of testing, monitoring, and deployment of newly added +code allows continuous deployment (CD) throughout the app lifecycle, +providing a comprehensive CI/CD approach. + +.. figure:: ../images/cicd.jpg + :width: 300pt + +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. +For more information, see `pytest usage `_. + +Here are some guidelines for creating good unit tests: + +- Assign long and descriptive names to tests. +- Use the `Codecov `_ tool to ensure that all implemented code is tested. +- Check that tests return the same results each time. +- Verify that tests are independent. +- Write tests that verify only one part of the code at a time. +- Make tests as short and fast as possible. + +`What makes a good unit test? `_ +is an exhaustive list of tips for creating good unit tests. + +Most PyMAPDL tests require a connection to a running instance of +MAPDL, which makes them integration tests. If your test +requires a running MAPDL instance, you can use the PyMAPDL +`mapdl `_ method in your function signature. +It is executed upstream of each test and not within all tests. + +.. code:: python + + def test_my_new_feature(mapdl): # pass the 'mapdl' fixture as an argument. + mapdl.prep7() + # .... more code + + 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. + +In Windows, use this code: + +.. code:: pwsh-session + + SET PYMAPDL_START_INSTANCE=False + SET PYMAPDL_PORT= (default 50052) + SET PYMAPDL_IP= (default 127.0.0.1) + +In Linux, use this code: + +.. code:: console + + export PYMAPDL_START_INSTANCE=False + export PYMAPDL_PORT= (default 50052) + export PYMAPDL_IP= (default 127.0.0.1) + +These environment variables tell PyMAPDL to attempt to connect to the existing +MAPDL service by default when the ``launch_mapdl`` function is used. + +Additionally, you can use the :envvar:`PYMAPDL_MAPDL_EXEC` and :envvar:`PYMAPDL_MAPDL_VERSION` +environment variables to specify the MAPDL executable path and the version to launch (if +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. +These tests are just some of the many in the `test directory `_. + +Here are some examples of how you use ``pytest``: + +.. code:: python + + import pytest + + + # 'cube_geom_and_mesh' is another fixture defined in 'conftest.py' + @pytest.fixture(scope="function") + def basic_components(mapdl, cube_geom_and_mesh): + """Given a model in 'cube_geom_and_mesh', define some components to work with later.""" + mapdl.components["mycomp1"] = "NODE", [1, 2, 3] + mapdl.components["mycomp2"] = "KP", [1, 3] + + mapdl.cmsel("s", "mycomp1") + mapdl.cmsel("a", "mycomp2") + + + def test_dunder_methods_keys(mapdl, basic_components): + assert ["MYCOMP1", "MYCOMP2"] == list(mapdl.components.names()) + + + def test_dunder_methods_types(mapdl, basic_components): + assert ["NODE", "KP"] == list(mapdl.components.types()) + + + def test_dunder_methods_items(mapdl, basic_components): + assert [("MYCOMP1", "NODE"), ("MYCOMP2", "KP")] == list(mapdl.components.items()) + + +For further explanations, see the `pytest documentation `_. + + + +Code style +========== + +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:: + + 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. For example:: + + $ pre-commit install + $ git commit -am "added my cool feature" + black....................................................................Passed + isort....................................................................Passed + flake8...................................................................Passed + codespell................................................................Passed + diff --git a/doc/source/getting_started/write_documentation.rst b/doc/source/getting_started/write_documentation.rst new file mode 100644 index 0000000000..7b03e0e9c4 --- /dev/null +++ b/doc/source/getting_started/write_documentation.rst @@ -0,0 +1,232 @@ +.. _write_documentation: + +=================== +Write documentation +=================== + +Writing documentation is an excellent way to contribute to a project because it +plays a pivotal role in making the project more accessible and usable. Clear and +comprehensive documentation empowers users and developers to understand, +implement, and troubleshoot the project effectively. It minimizes barriers to +entry, making it easier for newcomers to get involved and for existing +contributors to be more productive. + +Good documentation also reduces the burden on maintainers, +as it can answer common questions and help prevent issues. By +creating or improving documentation, you not only enhance the project's quality +but also facilitate knowledge sharing and community growth, making your +contribution invaluable for the project's long-term success. + +Set up your environment +======================= + +To be able to write and build the documentation, you must follow the same +steps described in :ref:`developing_pymapdl`, but in this case, you must install +documentation dependencies with this command: + +.. code:: console + + pip install -e '.[doc]' + + +Build the documentation +======================= + +PyMAPDL documentation is mainly written in reStructuredText +format, saved as ``.rst`` files in the ``doc/source`` directory. +The tool used to build the documentation from these reStructuredText files +is `Sphinx `_. + +Sphinx also build API documentation from source code as well as manages the +cross-referencing between different files, classes, methods, and more. +Additionally, it builds an `examples gallery `_, +where the capabilities of PyMAPDL can be showcased. + +The documentation can be built as HTML files or a single PDF file. + +To build the documentation as HTML files, you only need to run a single command. + +On Linux: + + +.. code:: console + + make -C doc html + +On Windows: + +.. code:: pwsh-session + + doc\make.bat html + +The HTML files for the documentation are written to the ``doc/_build/html`` directory. + +If you want to build the PDF documentation, you must first install +a LaTeX distribution like `MikTeX `_. You can then run this command: + +.. code:: console + + make -C doc pdf + +Running the command to build either HTML files or a PDF file runs the Python files in ``./examples`` in the repository root directory to generate the `examples gallery `_. +The result of running these examples is cached so that the only the changed files +are re-run the next time. + +The Sphinx configuration is in the file +`conf.py `_ in :file:`doc/source`. + + +Write documentation +=================== + +Writing good documentation for a GitHub repository is crucial to ensure that +users and contributors can understand, use, and contribute to PyMAPDL +effectively. + +Here's a short summary of how to write good documentation: + +#. **Use a consistent structure**: Organize your documentation with a clear and + consistent structure. Use headings, subheadings, and a table of contents if + necessary to help users navigate your documentation easily. + +#. **Explain configuration changes**: If you require configuration changes, provide + clear instructions on how to use this new configuration, along with examples and explanations + of why they are needed. + +#. **Usage Examples**: Include real-world usage examples, code snippets, and + explanations to demonstrate how users can make the most of PyMAPDL. + +#. **Document the API and code**: Thoroughly document each function, class, and method. Include + parameter descriptions, return values, and usage examples. Follow the + `numpydoc `_ convention for documenting code. + +#. **Tutorials and guides**: Create tutorials or guides to help users achieve + specific tasks or workflows with PyMAPDL. These can be especially + helpful for complex projects. + +#. **Troubleshooting and FAQs**: Anticipate common issues and provide solutions + in a troubleshooting section. Frequently asked questions (FAQs) can also be + helpful for addressing common queries. + +#. **Maintain and update**: Keep your documentation up to date as the project + evolves. New features, changes, and bug fixes should be reflected in the + documentation. + +#. **Solicit Feedback**: Invite users and contributors to provide feedback on + the documentation and be responsive to their suggestions and questions. + + +Vale linting tool +================= + +On the GitHub repository, the CI/CD runs `Vale `_, a powerful and extensible linting tool for +checking the writing of each pull request. +If you want to verify locally as well, you must install Vale locally: + +Installation +------------ + +#. **Install Vale**: Follow the instructions in `Installation `_ +#. **Verify installation**: To confirm that Vale is installed correctly, run this command: + + .. code:: console + + vale --version + + You should see the installed Vale version displayed in the terminal. + +Usage +----- + +Vale is a versatile tool for linting and style checking your documents, +supporting various file formats and providing a wide range of style guides. +Here's a basic example of how to use Vale in PyMAPDL: + +#. **Sync styles**: The first time you run Vale in a repository, you must + sync the styles specified in the :file:`.vale.ini` file by running this command: + + .. code:: console + + vale sync + + +#. **Lint Your Document**: To verify a document, run Vale from the command line, + specifying the file or directory you want to lint. For example: + + .. code:: console + + vale --config="./doc/.vale.ini" path/to/your_document.rst + + Vale analyzes your document, and if there are any style guide violations + or linting issues, it provides feedback in the terminal. + +Make sure you have no errors or warnings before opening your pull request. + + +.. _ref_building_example: + +Create an example +================= +There are three types of examples: dynamic, static, and semi-static. + +* `Dynamic examples`_ +* `Static examples`_ +* `Semi-dynamic examples`_ + + +Dynamic examples +---------------- + +Dynamic examples are based on Python files and must be able to run in under three minutes. + +In the PyMAPD repository, they are in the `examples `_ directory. + +.. vale off + +Example: `2d_plate_with_a_hole.py `_ +.. vale on + +Here is a link to this dynamic example: +`MAPDL 2D Plane Stress Concentration Analysis `_ + +When an example is executed, **Total running time of the script** appears at the end of +the document. + +Because dynamic examples must run each time the documentation is built, make sure that they are +very short. To get around the problem of execution time, feel free to use static or semi-static +examples. + + +Static examples +--------------- + +Static examples are based on RST files and are not executed. + +In the PyMAPDL repository, they are in the `doc\source `_ directory. +.. vale off + +Example: `krylov_example.rst `_ +.. vale on + +Here is a link to this static example: `Harmonic analysis using the frequency-sweep Krylov method `_ + + +Semi-dynamic examples +--------------------- + +Semi-dynamic examples are RST files that execute Python code using this RST directive: + +.. code:: rst + + .. jupyter-execute:: + :hide-code: + + +.. vale off + +Example: `tecfricstir.rst `_ +.. vale on + +Here is a link to this semi-dynamic example: `Friction Stir Welding (FSW) Simulation `_ + + diff --git a/doc/source/links.rst b/doc/source/links.rst index b1fb34392a..eb54e31635 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -22,6 +22,7 @@ .. _dev_guide_pyansys: https://dev.docs.pyansys.com .. _dev_guide_contributing: https://dev.docs.pyansys.com/how-to/contributing.html .. _dev_guide_coding_style: https://dev.docs.pyansys.com/coding-style/index.html +.. _dev_guide_setup_your_environment: https://dev.docs.pyansys.com/how-to/setting-up.html .. #Other libraries .. _pyvista_docs: https://docs.pyvista.org/version/stable/ @@ -108,6 +109,11 @@ .. _tds_article_web_app_1: https://towardsdatascience.com/ansys-in-a-python-web-app-part-1-post-processing-with-pydpf-44d2fbaa6135 .. _tds_article_web_app_2: https://towardsdatascience.com/ansys-in-a-python-web-app-part-2-pre-processing-solving-with-pymapdl-50428c18f8e7 .. _paraview_question_read_rst: https://discourse.paraview.org/t/reading-ansys-apdl-rst-results-in-paraview/9706 +.. _miktex: https://miktex.org +.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/ +.. _sphinx: https://www.sphinx-doc.org/en/master/ +.. _vale: https://www.vale.sh +.. _vale_installation: https://vale.sh/docs/vale-cli/installation/ .. #Github links: .. _gh_creating_pat: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token @@ -148,6 +154,10 @@ .. _pymapdl_discussion_differences_mapdl_pymapdl: https://github.com/ansys/pymapdl-reader/issues/185 .. _cartpole_example_notebook: https://cartpole.mapdl.docs.pyansys.com/ml-rl-notebook.html .. _wsl_launching_mapdl: https://github.com/ansys/pymapdl/issues/2315 +.. _pymapdl_examples_gallery: https://mapdl.docs.pyansys.com/version/stable/examples/index.html +.. _pymapdl_latest_github_release: https://github.com/ansys/pymapdl/releases/latest +.. _pymapdl_latest_pdf_doc: https://github.com/ansys/pymapdl/releases/download/v%%PYMAPDLVERSION%%.0/pymapdl-Documentation-%%PYMAPDLVERSION%%.0.pdf +.. _pymapdl_conf_file: https://github.com/ansys/pymapdl/blob/main/doc/source/conf.py .. _pymapdl_search_issues_pr: https://github.com/ansys/pymapdl/issues?q= .. _pymapdl_latest_github_release: https://github.com/ansys/pymapdl/releases/latest .. _pymapdl_latest_pdf_doc: https://github.com/ansys/pymapdl/releases/download/v%%PYMAPDLVERSION%%.0/pymapdl-Documentation-%%PYMAPDLVERSION%%.0.pdf diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index b007e0d9b0..38315fc3e9 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -34,8 +34,7 @@ script: You can attach this file to a bug report in the PyMAPDL GitHub repository for further investigation. If you are not able to identify the issue, you can open a discussion on the `PyMAPDL Discussions page `_. -If you believe you have found a bug, open an issue on the -`PyMAPDL Issues page `_. +If you believe you have found a bug, create an issue on the `PyMAPDL Issues page `_. .. _ref_launching_issue: diff --git a/doc/styles/Vocab/ANSYS/accept.txt b/doc/styles/Vocab/ANSYS/accept.txt index de0ee6a543..df7a82e475 100644 --- a/doc/styles/Vocab/ANSYS/accept.txt +++ b/doc/styles/Vocab/ANSYS/accept.txt @@ -1,10 +1,12 @@ [aA]nsys [Bb]ooleans [Cc]ommand [Pp]rompt +[Dd]ocker [Ee]igensolver [Hh]yperelasticity [Kk]eypoints [Mm]atplotlib +[Mm]ulti-[Ff]ield [Nn]umpy [Pp]ostprocess [Pp]ostprocessing @@ -14,6 +16,8 @@ [Pp]yansys [Pp]ythonic [Pp]ythonically +[Rs]ST +[Ss]ubsystem [Ss]uperelements [Vv]on Mises 2D @@ -46,8 +50,6 @@ Chao container_layout datas delet -docker -Docker dof ect eigenfrequency @@ -69,8 +71,8 @@ GPa GUI hexahedral hostname -Imagemagick -ImageMagick +HTML +Image[Mm]agick imagin importlib ist @@ -93,7 +95,6 @@ midside Mises mkdir MSc -Multi-[Ff]ield multipoint nce Newton-Raphson @@ -126,7 +127,6 @@ Radiosity Rao righ RNNN -RST singl smal sord @@ -134,7 +134,6 @@ spotweld struc subselected substep -Subsystem sur tablet thermomechanical