From d560c1ac174c845c7aa551383eeb2f1617650e2d Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 22 Oct 2024 15:18:27 +0200 Subject: [PATCH 01/42] add new basic tutorial and jupyter_ sphinx extension --- .../user_guide/tutorials/basic_tutorial.rst | 241 ++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 doc/source/user_guide/tutorials/basic_tutorial.rst diff --git a/doc/source/user_guide/tutorials/basic_tutorial.rst b/doc/source/user_guide/tutorials/basic_tutorial.rst new file mode 100644 index 00000000000..11b7097676d --- /dev/null +++ b/doc/source/user_guide/tutorials/basic_tutorial.rst @@ -0,0 +1,241 @@ +.. _ref_tutorials_basic: + +================== +The basic tutorial +================== + +This tutorial guides throughout the basic concepts and features of the PyDPF-Core tool. +It helps to have a Python interpreter for hands-on experience, but all code examples are +executed, so the tutorial can be read off-line as well. + +For a complete description of all the objects and modules, see the :ref:`API reference ` section. + +This page is divided in two sections: + +.. grid:: 1 1 2 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Overview + :link: tutorials_overview + :link-type: ref + :text-align: center + + Learn the different ways to interact with data by calling PyDPF-Core commands and operators. + + .. grid-item-card:: Postprocessing main steps + :link: tutorials_main_steps + :link-type: ref + :text-align: center + + How to do a basic prost-processing by transforming simulation data into output + data that can be used to visualize and analyze results + +.. _tutorials_overview: + +Overview +-------- + + + +.. _tutorials_main_steps: + +Postprocessing main steps +------------------------- + +There are five main steps to transform simulation data into output data that can +be used to visualize and analyze simulation results: + +.. grid:: + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: 1 + :link: tutorials_main_steps_1 + :link-type: ref + :text-align: center + + Importing and opening results files + + .. grid-item-card:: 2 + :link: tutorials_main_steps_2 + :link-type: ref + :text-align: center + + Access and extract results + + .. grid-item-card:: 3 + :link: tutorials_main_steps_3 + :link-type: ref + :text-align: center + + Transform available data + + .. grid-item-card:: 4 + :link: tutorials_main_steps_4 + :link-type: ref + :text-align: center + + Visualize the data + + .. grid-item-card:: 5 + :link: tutorials_main_steps_5 + :link-type: ref + :text-align: center + + Extract data + +.. _tutorials_main_steps_1: + +1- Importing and opening results files +************************************** + +First, import the DPF-Core module as ``dpf`` and import the included examples file + +.. code-block:: python + + from ansys.dpf import core as dpf + from ansys.dpf.core import examples + from ansys.dpf.core import operators as ops + +`DataSources' is a class that manages paths to their files. Use this object to declare +data inputs for DPF and define their locations. + +.. code-block:: python + + # Define the DataSources object + my_data_sources = dpf.DataSources(result_path=examples.find_simple_bar()) + + +The model is a helper designed to give shortcuts to access the analysis results +metadata, by opening a DataSources or a Streams, and to instanciate results provider for it. + +Printing the model displays: + + - Analysis type + - Available results + - Size of the mesh + - Number of results + +.. code-block:: python + + # Define the Model object + my_model = dpf.Model(data_sources=my_data_sources) + print(my_model) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + from ansys.dpf import core as dpf + from ansys.dpf.core import examples + from ansys.dpf.core import operators as ops + my_data_sources = dpf.DataSources(result_path=examples.find_simple_bar()) + my_model = dpf.Model(data_sources=my_data_sources) + print(my_model) + +.. _tutorials_main_steps_2: + +2- Access and extract results +***************************** + +We see in the model that a displacement result is available. You can access this result by: + +.. code-block:: python + + # Define the displacement results through the models property `results` + my_displacements = my_model.results.displacement.eval() + print(my_displacements) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_displacements = my_model.results.displacement.eval() + print(my_displacements) + +The displacement data can be extract by: + +.. code-block:: python + + # Extract the data of the displacement field + my_displacements_0 = my_displacements[0].data + print(my_displacements_0) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_displacements_0 = my_displacements[0].data + print(my_displacements_0) + +.. _tutorials_main_steps_3: + +3- Transform available data +*************************** + +Several transformations can be made with the data. They can be a single operation, +by using only one operator, or they can represent a succession of operations, by defining a +workflow with chained operators. + +Here we star by computing the displacements norm. + +.. code-block:: python + + # Define the norm operator (here for a fields container) for the displacement + my_norm = ops.math.norm_fc(fields_container=my_displacements).eval() + print(my_norm[0].data) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_norm = ops.math.norm_fc(fields_container=my_displacements).eval() + print(my_norm[0].data) + +Then we compute the maximum values of the normalised displacement + +.. code-block:: python + + # Define the maximum operator and chain it to the norm operator + my_max= ops.min_max.min_max_fc(fields_container=my_norm).outputs.field_max() + print(my_max) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_max = ops.min_max.min_max_fc(fields_container=my_norm).outputs.field_max() + print(my_max) + +.. _tutorials_main_steps_4: + +4- Visualize the data +********************* + +Plot the transformed displacement results + +.. code-block:: python + + # Define the support of the plot (here we plot the displacement over the mesh) + my_model.metadata.meshed_region.plot(field_or_fields_container=my_displacements) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_model.metadata.meshed_region.plot(field_or_fields_container=my_displacements) + +.. _tutorials_main_steps_5: + +5- Extract the data +******************* + From 37ee211060b6dca602306a5ef086142898e71a5e Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 27 Nov 2024 11:59:31 +0100 Subject: [PATCH 02/42] separate the documentation part from the contributing.rst (main page) --- doc/source/getting_started/contributing.rst | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/doc/source/getting_started/contributing.rst b/doc/source/getting_started/contributing.rst index 1f7ac56da0c..94928b56e54 100644 --- a/doc/source/getting_started/contributing.rst +++ b/doc/source/getting_started/contributing.rst @@ -30,12 +30,4 @@ page to submit questions, report bugs, and request new features. To reach the project support team, email `pyansys.core@ansys.com `_. -View documentation ------------------- -Documentation for the latest stable release of PyDPF-Core is hosted at -`PyDPF-Core 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. +.. include:: write_doc/index.rst From de29b4825b7d3b0d6589472844dd0b0815513443 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 27 Nov 2024 12:02:19 +0100 Subject: [PATCH 03/42] create the index page for the writing documentation section --- .../getting_started/write_doc/index.rst | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 doc/source/getting_started/write_doc/index.rst diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst new file mode 100644 index 00000000000..245aa057a61 --- /dev/null +++ b/doc/source/getting_started/write_doc/index.rst @@ -0,0 +1,80 @@ +.. _ref_write_doc: + +Documentation +------------- + +The PyDPF-Core documentation 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. + +Write documentation +^^^^^^^^^^^^^^^^^^^ + +Writing good documentation for a GitHub repository is crucial to ensure that +users and contributors can understand, use, and contribute to PyDPF-Core +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. + +#. **Use Sphinx properly**: Sphinx has multiple features and directives. Before + starting to write documentation, you should get familiar with it. For guidance, + see these Sphinx and DocUtils topics: `Directives `_, + `reStructuredText Primer `_ and + `reStructuredText Directives `_. + +#. **Usage Examples**: Include real-world usage examples, code snippets, and + explanations to demonstrate how users can make the most of PyDPF-Core. + +#. **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 PyDPF-Core. + +#. **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. + + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Writing tutorials + :link: ref_guide_lines_tutorials + :link-type: ref + :text-align: center + + Here you find the guide lines that must be followed to write new tutorials. + You also have templates to help you doing this task. + + + +View documentation +^^^^^^^^^^^^^^^^^^ +Documentation for the latest stable release of PyDPF-Core is hosted at +`PyDPF-Core 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. \ No newline at end of file From 727b98641fea4cd94e55984a5a4d240b333a784e Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 27 Nov 2024 12:02:49 +0100 Subject: [PATCH 04/42] add the tutorials guide lines file --- .../write_doc/guide_lines_tutorials.rst | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 doc/source/getting_started/write_doc/guide_lines_tutorials.rst diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst new file mode 100644 index 00000000000..881c24c6234 --- /dev/null +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -0,0 +1,38 @@ +.. _ref_guide_lines_tutorials: + +============================= +Writing tutorials guide lines +============================= + +To add a tutorial on the documentation you need to follow the guide lines presented here. + +Adding a new tutorial section +----------------------------- + +.. note:: + + Avoid creating new folders unless absolutely necessary. If in doubt, its precise location can be advised + on in the pull request. If you must create a new folder, make sure to add a ``index.rst`` file containing + a reference, tue section title and a description of the section. Otherwise the new folder will be ignored by Sphinx. + + + +Adding a new tutorial +--------------------- +Location and naming +^^^^^^^^^^^^^^^^^^^ + +New tutorials must be added as ``.rst`` files to: ``doc/source/user_guide/tutorials/section_name/tutorial_file.rst`` + + +Structure +^^^^^^^^^ + +The tutorial needs to have the following parts: + +- Introduction +- +- + +Content +^^^^^^^ From 9140d970902926269f9c188288d2e83add305111 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 27 Nov 2024 12:03:02 +0100 Subject: [PATCH 05/42] add the tutorial template file --- .../getting_started/write_doc/tutorial_template.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 doc/source/getting_started/write_doc/tutorial_template.rst diff --git a/doc/source/getting_started/write_doc/tutorial_template.rst b/doc/source/getting_started/write_doc/tutorial_template.rst new file mode 100644 index 00000000000..a3f29ae7a0c --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_template.rst @@ -0,0 +1,13 @@ +.. _ref_tutorial_template: + +============== +Tutorial title +============== + +.. |Examples| replace:: :class:`ansys.dpf.core.examples` + +This sentence resumes the goal of the tutorial + +Introduction to the tutorial + +:jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` From f804a345331d44abeb910fec53dddcb814bcec91 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Thu, 28 Nov 2024 12:06:52 +0100 Subject: [PATCH 06/42] updates the contributing.rst main page --- doc/source/getting_started/contributing.rst | 92 +++++++++++++++++---- 1 file changed, 76 insertions(+), 16 deletions(-) diff --git a/doc/source/getting_started/contributing.rst b/doc/source/getting_started/contributing.rst index 94928b56e54..1fffb4dfe95 100644 --- a/doc/source/getting_started/contributing.rst +++ b/doc/source/getting_started/contributing.rst @@ -4,30 +4,90 @@ Contributing ============ +There are several ways to contribute to PyDPF-Core: + +- :ref:`ref_contributing_answer_discussions` +- :ref:`ref_contributing_post_issues` +- :ref:`ref_contributing_develop_code` +- :ref:`ref_contributing_improve_doc` + Overall guidance on contributing to a PyAnsys repository appears in -`Contribute `_ -in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar -with this guide before attempting to contribute to PyDPF-Core. - +`Contributing `_ in the *PyAnsys Developer's Guide*. +Ensure that you are thoroughly familiar with this guide before attempting +to contribute to PyDPF-Core. + The following contribution information is specific to PyDPF-Core. -Clone the repository --------------------- -Clone and install the latest version of PyDPF-Core in -development mode by running this code: +.. _ref_contributing_answer_discussions: -.. code:: +Answer discussions +------------------ - git clone https://github.com/ansys/pydpf-core - cd pydpf-core - pip install -e . +Answering discussions is an excellent way to contribute to PyDPF-Core, and it does not require +any setup, just a GitHub account. 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 `PyDPF-Core Discussions page `_. + +.. _ref_contributing_post_issues: Post issues ----------- -Use the `PyDPF-Core Issues `_ -page to submit questions, report bugs, and request new features. -To reach the project support team, email `pyansys.core@ansys.com `_. +Posting issues in a repository 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. + +Use the `PyDPF-Core 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; +- 🎓 Adding an tutorial: Proposing a new tutorial for the library; +- 💡 New feature: Enhancements to the code; +- If your issue does not fit into one of these categories create a blank issue. + +To reach the project support team, email `pyansys.core@ansys.com `_ + +.. _ref_contributing_develop_code: + +Develop code +------------ + +You can help improve PyDPF-Core by fixing a bug. To do it, you must set up the repository on your local +machine as per the explanations in the :ref:`ref_write_code` section. + + +.. _ref_contributing_improve_doc: + +Improve documentation +--------------------- + +The PyDPF-Core documentation 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. + +To contribute on our current documentation go to the :ref:`ref_write_doc` section. + +.. toctree:: + :maxdepth: 2 + :hidden: + + write_doc/index.rst + write_code/index.rst + + -.. include:: write_doc/index.rst From 2d327d46635ecaa854e8d1945f5712c3e0c6adb3 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Thu, 28 Nov 2024 12:07:40 +0100 Subject: [PATCH 07/42] add a separate section for develop code (contributing) --- .../getting_started/write_code/index.rst | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 doc/source/getting_started/write_code/index.rst diff --git a/doc/source/getting_started/write_code/index.rst b/doc/source/getting_started/write_code/index.rst new file mode 100644 index 00000000000..8de86c95b31 --- /dev/null +++ b/doc/source/getting_started/write_code/index.rst @@ -0,0 +1,101 @@ +.. _ref_write_code: + +============ +Develop code +============ + +You can help improve PyDPF-Core by fixing a bug. To do it, you must set up the repository +on your local machine as per the following steps: + +- :ref:`ref_write_code_clone` +- :ref:`ref_write_code_check_install` +- :ref:`ref_write_code_develop_code` + +.. _ref_write_code_clone: + +Clone the repository +-------------------- + +Before cloning the PyMAPDL repository, you must install a version control system such as Git. + +Then, clone and install the latest version of PyDPF-Core in development mode (using ``pip`` with the ``-e`` +development flag) by running this code: + +.. code:: + + git clone https://github.com/ansys/pydpf-core + cd pydpf-core + pip install -e . + +.. _ref_write_code_check_install: + +Check the installation +---------------------- + +Run the following Python code to verify your PyDPF-Core installation: + +.. code:: + + from ansys.dpf.core import Model + from ansys.dpf.core import examples + model = Model(examples.find_simple_bar()) + print(model) + +.. _ref_write_code_develop_code: + +Develop the PyDPF-Core code +--------------------------- + +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. For example, the branch name must start with a prefix and a backslash. + +#. **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. + Pull requests must follow the same convention as the commit messages. + + The pull requests can also be labeled for easier repository maintenance. + Those labels are already defined in the repository. + +#. **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. + +#. **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/pydpf-admins`` 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. \ No newline at end of file From aefe14265d6647cd50ed623181d666de8fc1cab8 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Thu, 28 Nov 2024 16:15:55 +0100 Subject: [PATCH 08/42] add the writing documentation index page --- .../getting_started/write_doc/index.rst | 129 ++++++++++++++---- 1 file changed, 105 insertions(+), 24 deletions(-) diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index 245aa057a61..f38a81c16a9 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -1,20 +1,8 @@ .. _ref_write_doc: +============= Documentation -------------- - -The PyDPF-Core documentation 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. - -Write documentation -^^^^^^^^^^^^^^^^^^^ +============= Writing good documentation for a GitHub repository is crucial to ensure that users and contributors can understand, use, and contribute to PyDPF-Core @@ -42,9 +30,8 @@ Here's a short summary of how to write good documentation: #. **Tutorials and guides**: Create tutorials or guides to help users achieve specific tasks or workflows with PyDPF-Core. -#. **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. +#. **Troubleshooting**: Anticipate common issues and provide solutions + in a troubleshooting section. #. **Maintain and update**: Keep your documentation up to date as the project evolves. New features, changes, and bug fixes should be reflected in the @@ -53,24 +40,118 @@ Here's a short summary of how to write good documentation: #. **Solicit Feedback**: Invite users and contributors to provide feedback on the documentation and be responsive to their suggestions and questions. +To improve the documentation you need to: + +- Start by `cloning the repository `_; +- Follow the `guidelines `_ to the corresponding documentation part you want to develop; +- Check the new documentation by `viewing the documentaion `_ + +Clone the repository +-------------------- +Clone and install the latest version of PyDPF-Core in +development mode by running this code: + +.. code:: + + git clone https://github.com/ansys/pydpf-core + cd pydpf-core + pip install -e . + + +Guidelines +---------- -.. grid:: 1 1 3 3 +Our documentation tries to follow a structure principle that respects four different functions of the documentation +that fulfils the possible needs of people working with our tool at different times, in different circumstances. + +Here is an overview of how our documentation is organized to help you know where you should include your contributions. +Each section has their own guidelines that must be followed when creating new content. + +.. grid:: 1 1 2 2 :gutter: 2 :padding: 2 :margin: 2 - .. grid-item-card:: Writing tutorials + .. grid-item-card:: **TUTORIALS** :link: ref_guide_lines_tutorials :link-type: ref - :text-align: center + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Learning oriented + ^^^^^^^^^^^^^^^^^ + + **Function:** Teach how to get started and use PYDPF-core step by step + + They are designed to teach how to perform a task and understand the underlying concepts, + providing detailed explanations at each stage. + + +++ + .. rubric:: Guidelines + + Here you find guidelines and templates to write new tutorials. + + .. grid-item-card:: **EXAMPLES** + :link: ref + :link-type: ref + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Use-cases oriented + ^^^^^^^^^^^^^^^^^^ + + **Function:** Show how to solve specifics key problems + + They showcase specific key problems and use-cases. They are more advanced than + tutorials and assume some knowledge on PyDPF-Core. + + +++ + .. rubric:: Guidelines + + Here you find guidelines and templates to write new examples. + + .. grid-item-card:: **CONCEPTS** + :link: ref + :link-type: ref + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Understanding oriented + ^^^^^^^^^^^^^^^^^^^^^^ + + **Function:** Provide useful background explanation on PyDPF-Core + + They discuss and explain key topics and concepts providing enabling the reader to understand our + tool. + + +++ + .. rubric:: Guidelines + + Here you find guidelines and templates to write more concepts. + + + .. grid-item-card:: **API REFERENCE** + :link: ref + :link-type: ref + :class-title: sd-text-center sd-bg-light + :class-header: sd-text-center + + Informing oriented + ^^^^^^^^^^^^^^^^^^ + + **Function:** Describe PyDPF-Core APIs + + They contain technical reference on how PyDPF-Core works and how to use it but assume that you have + a basic understanding of key concepts. - Here you find the guide lines that must be followed to write new tutorials. - You also have templates to help you doing this task. + +++ + .. rubric:: Guidelines + Here you find guidelines and templates to improve the API reference. +View the documentation +---------------------- -View documentation -^^^^^^^^^^^^^^^^^^ Documentation for the latest stable release of PyDPF-Core is hosted at `PyDPF-Core Documentation `_. From b1d228020f9adb85fe890a5536a7683a5e85c1ef Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Thu, 28 Nov 2024 16:16:27 +0100 Subject: [PATCH 09/42] add new links to links_and_refs.rst --- doc/source/links_and_refs.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/source/links_and_refs.rst b/doc/source/links_and_refs.rst index 1bb88ec64a7..2257acdcd4f 100644 --- a/doc/source/links_and_refs.rst +++ b/doc/source/links_and_refs.rst @@ -2,6 +2,10 @@ .. LINKS +.. PyDPF-Core +.. _pydpfcore_issues: https://github.com/ansys/pydpf-core/issues +.. _pydpfcore_discussions: https://github.com/ansys/pydpf-core/discussions + .. Pyansys .. _pyansys: https://docs.pyansys.com/version/dev/ From ffb864639a60695cfd0a2ee7e1a56b21dfdb29c5 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Fri, 29 Nov 2024 17:14:40 +0100 Subject: [PATCH 10/42] add tutorial_card_template.rst --- .../write_doc/tutorial_card_template.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 doc/source/getting_started/write_doc/tutorial_card_template.rst diff --git a/doc/source/getting_started/write_doc/tutorial_card_template.rst b/doc/source/getting_started/write_doc/tutorial_card_template.rst new file mode 100644 index 00000000000..05a77257c88 --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_card_template.rst @@ -0,0 +1,14 @@ +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Tutorial title + :link: ref + :link-type: ref + :text-align: center + + This tutorial ... + + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` \ No newline at end of file From 43309763f3ec2090196ea385bf36148becbe25a2 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Fri, 29 Nov 2024 17:14:55 +0100 Subject: [PATCH 11/42] add tutorial_section_template.rst --- .../write_doc/tutorial_section_template.rst | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 doc/source/getting_started/write_doc/tutorial_section_template.rst diff --git a/doc/source/getting_started/write_doc/tutorial_section_template.rst b/doc/source/getting_started/write_doc/tutorial_section_template.rst new file mode 100644 index 00000000000..16ea42a6a32 --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_section_template.rst @@ -0,0 +1,28 @@ +.. _ref_tutorial_new_section_template: + +============= +Section title +============= + +These tutorials demonstrate how to ... + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Tutorial title + :link: ref + :link-type: ref + :text-align: center + + This tutorial ... + + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` + +.. toctree:: + :maxdepth: 2 + :hidden: + + tutorial_file.rst \ No newline at end of file From 18d71fdc534053b882cfb01ed24e262c3cb70146 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Fri, 29 Nov 2024 17:20:11 +0100 Subject: [PATCH 12/42] add toctree to index file of the write_doc folder --- doc/source/getting_started/write_doc/index.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index f38a81c16a9..6e882e94185 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -158,4 +158,10 @@ Documentation for the latest stable release of PyDPF-Core is hosted at 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. \ No newline at end of file +released versions. + +.. toctree:: + :maxdepth: 2 + :hidden: + + guide_lines_tutorials.rst From 8e8d7d92c95ee3b1867eef8dec742833929e3e64 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Fri, 29 Nov 2024 17:49:14 +0100 Subject: [PATCH 13/42] add first part of the guide_lines_tutorials.rst --- .../write_doc/guide_lines_tutorials.rst | 188 +++++++++++++++++- 1 file changed, 179 insertions(+), 9 deletions(-) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index 881c24c6234..8d4cc19692b 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -4,10 +4,37 @@ Writing tutorials guide lines ============================= -To add a tutorial on the documentation you need to follow the guide lines presented here. +You can improve the Py-DPF-Core documentation by adding: +- :ref:`New tutorials sections`; +- :ref:`New tutorials`. + +To do so, you must follow the guide lines presented here. +You also need to understand the structure of the ``doc`` directory on the PyDPF-Core library: + +.. code-block:: + + . + ├── doc + │ ├── source + │ │ ├── api + │ │ ├── examples + │ │ ├── getting_started + │ │ ├── images + │ │ ├── user_guide + │ │ ├── conf.py + │ │ ├── index.rst + │ ├── styles + │ ├── make.bat + + +You will be handling only the ``doc/source/user_guide`` directory . + +.. _ref_guide_lines_add_new_tutorial_section: + +============================= Adding a new tutorial section ------------------------------ +============================= .. note:: @@ -15,24 +42,167 @@ Adding a new tutorial section on in the pull request. If you must create a new folder, make sure to add a ``index.rst`` file containing a reference, tue section title and a description of the section. Otherwise the new folder will be ignored by Sphinx. +Location and naming +------------------- + +The new tutorial section must be organized in a new folder in ``doc/source/user_guide/tutorials/new_section_name``. + +.. code-block:: + + . + ├── doc + │ ├── source + │ │ ├── user_guide + │ │ │ ├── tutorials + │ │ │ ├── new_section + +Structure +--------- + +The new folder must contain at least a ``index.rst`` file. This file has: + +- Reference name; +- Section title; +- General description of the content of the tutorials in this section; +- Cards with the tutorial title, description and applicable solvers (the card must have a link to the tutorial file); +- Toctree with the tutorials in the section. +You must also add the ``index.rst`` file. in the main user guide toctree. You can find it at the end of +``doc/source/user_guide/index.rst`` file. +.. rubric:: Templates + +:download:`Download the new tutorial section template` + +.. _ref_guide_lines_add_new_tutorial: + +===================== Adding a new tutorial ---------------------- +===================== + Location and naming -^^^^^^^^^^^^^^^^^^^ +------------------- New tutorials must be added as ``.rst`` files to: ``doc/source/user_guide/tutorials/section_name/tutorial_file.rst`` +.. code-block:: + + . + ├── doc + │ ├── source + │ │ ├── user_guide + │ │ │ ├── tutorials + │ │ │ ├── section + │ │ │ ├── new_tutorial.rst + +You also have to add it to a card and the toctree on the section ``index.rst`` file. The card must have: + +- Tutorial title; +- Short description; +- Applicable solvers; +- Link to the tutorial file; + +.. card:: Tutorial title + :text-align: center + :width: 25% + + Short description of the tutorial + + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` + +.. rubric:: Templates + +:download:`Download the card template` Structure -^^^^^^^^^ +--------- + +The tutorial structure can be divided in two main parts: + +- Basis; +- Content. + +Basis +^^^^^ + +This first part must have the following components: + +- File reference name; +- Tutorial title; +- Substitution text for the PyDPF-Core library references; +- Short description (same phrase used in the tutorial card in the tutorial section ``index.rst`` file); +- Introduction that explains the context of the tutorial; +- Download script buttons; -The tutorial needs to have the following parts: +.. code-block:: -- Introduction -- -- + .. _ref_tutorial_template: + + + ============== + Tutorial title + ============== + + + .. |Examples| replace:: :class:`ansys.dpf.core.examples` + + + This sentence resumes the goal of the tutorial + + + Introduction to the tutorial + + + :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` Content ^^^^^^^ + +A tutorial goal is to explain how to perform a task step by step and understand the underlying concepts. + +Sections +~~~~~~~~ + +A well-structured tutorial content should be divided by those steps. For example: + +A tutorial goal is to explains how to plot a mesh using PyDPF-Core. +The steps to achieve this task are: + +- Import a result file; +- Extract the mesh; +- Plot the mesh. + +To create those section, underline it with the appropriate characters (here: ``-``). + +.. code-block:: + + Import result file + ------------------ + + First, you ... + + + Extract the mesh + ---------------- + + Then, you extract ... + + + Plot the mesh + ------------- + + Finally, you plot ... + +Code snippets +~~~~~~~~~~~~~ + +Text formating +~~~~~~~~~~~~~~ + + + + + + + From 023c831b1e0e2146f0e0090201e33fa77d76fe4e Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 3 Dec 2024 10:19:37 +0100 Subject: [PATCH 14/42] updates --- .../write_doc/guide_lines_tutorials.rst | 241 ++++++++++++++++-- .../write_doc/tutorial_template.rst | 46 ++++ 2 files changed, 264 insertions(+), 23 deletions(-) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index 8d4cc19692b..5f06eeb3187 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -1,13 +1,13 @@ .. _ref_guide_lines_tutorials: -============================= -Writing tutorials guide lines -============================= +============================ +Writing tutorials guidelines +============================ -You can improve the Py-DPF-Core documentation by adding: +You can improve the Py-DPF-Core documentation by adding a: -- :ref:`New tutorials sections`; -- :ref:`New tutorials`. +- :ref:`New tutorials section`; +- :ref:`New tutorial`. To do so, you must follow the guide lines presented here. You also need to understand the structure of the ``doc`` directory on the PyDPF-Core library: @@ -38,9 +38,9 @@ Adding a new tutorial section .. note:: - Avoid creating new folders unless absolutely necessary. If in doubt, its precise location can be advised - on in the pull request. If you must create a new folder, make sure to add a ``index.rst`` file containing - a reference, tue section title and a description of the section. Otherwise the new folder will be ignored by Sphinx. + Avoid creating new folders unless it is absolutely necessary. If you are in doubt, its precise location can be + advised on the pull request. If you must create a new folder, make sure to add a ``index.rst`` file containing + a reference, a title and a description of the section. Otherwise the new folder will be ignored by Sphinx. Location and naming ------------------- @@ -67,7 +67,38 @@ The new folder must contain at least a ``index.rst`` file. This file has: - Cards with the tutorial title, description and applicable solvers (the card must have a link to the tutorial file); - Toctree with the tutorials in the section. -You must also add the ``index.rst`` file. in the main user guide toctree. You can find it at the end of +.. code-block:: + + .. _ref_tutorial_new_section_template: + + ============= + Section title + ============= + + These tutorials demonstrate how to ... + + .. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Tutorial title + :link: ref + :link-type: ref + :text-align: center + + This tutorial ... + + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` + + .. toctree:: + :maxdepth: 2 + :hidden: + + tutorial_file.rst + +You must also add the ``index.rst`` file in the main user guide page toctree. You can find it at the end of ``doc/source/user_guide/index.rst`` file. .. rubric:: Templates @@ -95,11 +126,11 @@ New tutorials must be added as ``.rst`` files to: ``doc/source/user_guide/tutori │ │ │ ├── section │ │ │ ├── new_tutorial.rst -You also have to add it to a card and the toctree on the section ``index.rst`` file. The card must have: +You also have to add it to a card and the toctree on the tutorial section ``index.rst`` file. The card must have: - Tutorial title; - Short description; -- Applicable solvers; +- Badges with the applicable solvers; - Link to the tutorial file; .. card:: Tutorial title @@ -120,17 +151,24 @@ Structure The tutorial structure can be divided in two main parts: -- Basis; +- Preamble; - Content. -Basis -^^^^^ +Preamble +^^^^^^^^ + +This first part is essential for clarity, organization and usability of the tutorial. It establishes the tutorials +purpose, making it easy to understand what is going to be explained and reference it within the other parts of +the documentation. + +Components +~~~~~~~~~~ -This first part must have the following components: +The preamble must have the following components: - File reference name; - Tutorial title; -- Substitution text for the PyDPF-Core library references; +- Substitution text for the PyDPF-Core library references that will be used across the tutorial; - Short description (same phrase used in the tutorial card in the tutorial section ``index.rst`` file); - Introduction that explains the context of the tutorial; - Download script buttons; @@ -156,22 +194,51 @@ This first part must have the following components: :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` +The main PyDPF-Core library references are available already defined in the ``doc/source/links_and_refs.rst`` file. +To use it you use the include directive and use the substitution text as usual: + +.. code-block:: + + .. _ref_tutorial_template: + + + ============== + Tutorial title + ============== + + .. include:: ../../../links_and_refs.rst + + Here some text. Here we use the |MeshedRegion| substitution text + +For more information on those references check the :download:`links and references file<../../links_and_refs.rst>`. + Content ^^^^^^^ A tutorial goal is to explain how to perform a task step by step and understand the underlying concepts. +Thus, its structure must prioritize clarity, simplicity, and logical flow. Sections ~~~~~~~~ -A well-structured tutorial content should be divided by those steps. For example: +A well-organized tutorial breaks down complex tasks into manageable steps, presenting information incrementally +to avoid overwhelming the user. It combines concise explanations with actionable instructions, ensuring users +can follow along easily while building their understanding. + +Thus, the sections of the content are the steps themselves. Globally those steps looks like: + +#. Get data, define DPF objects that contains the data; +#. One or more steps where you manipulate, handles the data/ DPF objects; +#. Conclusion, here is the final step where the tutorial goal is accomplished. + +For example: A tutorial goal is to explains how to plot a mesh using PyDPF-Core. The steps to achieve this task are: -- Import a result file; -- Extract the mesh; -- Plot the mesh. +#. Import a result file; +#. Extract the mesh; +#. Plot the mesh. To create those section, underline it with the appropriate characters (here: ``-``). @@ -194,8 +261,136 @@ To create those section, underline it with the appropriate characters (here: ``- Finally, you plot ... -Code snippets -~~~~~~~~~~~~~ +Tabs +~~~~ + +You must use tabs in the case the tutorial is applicable fore more then one solver and the implementations are +different for each of them. + +These tabs looks like: + +.. tab-set:: + + .. tab-item:: MAPDL + + Explanation 1 ... + + .. jupyter-execute:: + + # Code block 1 + + .. tab-item:: LSDYNA + + Explanation 2 ... + + .. jupyter-execute:: + + # Code block 2 + + .. tab-item:: Fluent + + Explanation 3 ... + + .. jupyter-execute:: + + # Code block 3 + + .. tab-item:: CFX + + Explanation 4 ... + + .. jupyter-execute:: + + # Code block 4 + + +You can also use tabs if you want to show different approaches to one step and it would be more clear +to have the code blocks in different tabs. You can see an example of this case in the +:ref:`ref_tutorials_animate_time` tutorial. + + +Code blocks +~~~~~~~~~~~ + +The tutorials must have code blocks where you show how you actually implement the coode. +The guidelines for the code snippets are: + +- Use the `jupyter sphinx`_ extension. Its executes embedded code in a Jupyter kernel, + and embeds outputs of that code in the document: + +.. code-block:: + + .. jupyter-execute:: + + # This is a executable code block + from ansys.dpf import core as dpf + +- You must split your code in several parts so you can make explanations between them: + +First explanation + +.. code-block:: + + # Code block 1 + +Second explanation + +.. code-block:: + + # Code block 2 + + +- Every code implementation must be commented: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item:: + + **Correct** + + .. code-block:: + + # Define the model + model = dpf.Model() + # Get the stress results + stress_fc = model.results.stress.eval() + + .. grid-item:: + + **Incorrect** + + .. code-block:: + + model = dpf.Model() + stress_fc = model.results.stress.eval() + +- When using a PyDPF-Core object or method you must use key arguments + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item:: + + **Correct** + + .. code-block:: + + # Get the stress results + stress_fc = model.results.stress(time_scoping=time_steps).eval() + + .. grid-item:: + + **Incorrect** + + .. code-block:: + + # Get the stress results + stress_fc = model.results.stress(time_steps).eval() Text formating ~~~~~~~~~~~~~~ diff --git a/doc/source/getting_started/write_doc/tutorial_template.rst b/doc/source/getting_started/write_doc/tutorial_template.rst index a3f29ae7a0c..f0f1a5879e2 100644 --- a/doc/source/getting_started/write_doc/tutorial_template.rst +++ b/doc/source/getting_started/write_doc/tutorial_template.rst @@ -11,3 +11,49 @@ This sentence resumes the goal of the tutorial Introduction to the tutorial :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` + +First Step +---------- + +Here you have to make an implementation but it is different for the different solvers + +.. tab-set:: + + .. tab-item:: MAPDL + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: LSDYNA + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: Fluent + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: CFX + + Explanation ... + + .. jupyter-execute:: + + # Code block + +Second step +----------- + +Final Step +---------- + From ed18ffa8a958c262d8e8ca7a6ee46700fde4bd2f Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 3 Dec 2024 11:53:08 +0100 Subject: [PATCH 15/42] final first version of guide_lines_tutorials.rst --- .../write_doc/guide_lines_tutorials.rst | 179 ++++++++++++++---- 1 file changed, 141 insertions(+), 38 deletions(-) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index 5f06eeb3187..4e08ad8a789 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -36,6 +36,8 @@ You will be handling only the ``doc/source/user_guide`` directory . Adding a new tutorial section ============================= +:download:`Download the new tutorial section template` + .. note:: Avoid creating new folders unless it is absolutely necessary. If you are in doubt, its precise location can be @@ -101,16 +103,14 @@ The new folder must contain at least a ``index.rst`` file. This file has: You must also add the ``index.rst`` file in the main user guide page toctree. You can find it at the end of ``doc/source/user_guide/index.rst`` file. -.. rubric:: Templates - -:download:`Download the new tutorial section template` - .. _ref_guide_lines_add_new_tutorial: ===================== Adding a new tutorial ===================== +:download:`Download the tutorial card template` :download:`Download the tutorial template` + Location and naming ------------------- @@ -133,26 +133,26 @@ You also have to add it to a card and the toctree on the tutorial section ``inde - Badges with the applicable solvers; - Link to the tutorial file; -.. card:: Tutorial title - :text-align: center - :width: 25% - - Short description of the tutorial +.. topic:: Card example - +++ - :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` + .. card:: Tutorial title + :text-align: center + :width: 25% -.. rubric:: Templates + Short description of the tutorial -:download:`Download the card template` + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` Structure --------- The tutorial structure can be divided in two main parts: -- Preamble; -- Content. +- :ref:`Preamble`; +- :ref:`Content`. + +.. _ref_guide_lines_tutorial_preamble: Preamble ^^^^^^^^ @@ -195,7 +195,7 @@ The preamble must have the following components: :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` The main PyDPF-Core library references are available already defined in the ``doc/source/links_and_refs.rst`` file. -To use it you use the include directive and use the substitution text as usual: +To employ them, you use the ``include`` directive and use the substitution text as usual: .. code-block:: @@ -212,6 +212,8 @@ To use it you use the include directive and use the substitution text as usual: For more information on those references check the :download:`links and references file<../../links_and_refs.rst>`. +.. _ref_guide_lines_tutorial_content: + Content ^^^^^^^ @@ -315,30 +317,35 @@ Code blocks The tutorials must have code blocks where you show how you actually implement the coode. The guidelines for the code snippets are: -- Use the `jupyter sphinx`_ extension. Its executes embedded code in a Jupyter kernel, - and embeds outputs of that code in the document: +- Use the `jupyter sphinx`_ extension to show code blocks. Its executes embedded code in + a Jupyter kernel and embeds outputs of that code in the document: -.. code-block:: +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 - .. jupyter-execute:: + .. grid-item-card:: - # This is a executable code block - from ansys.dpf import core as dpf + :octicon:`check-circle-fill` **Correct** -- You must split your code in several parts so you can make explanations between them: + .. code-block:: -First explanation + .. jupyter-execute:: -.. code-block:: + # This is a executable code block + from ansys.dpf import core as dpf - # Code block 1 + .. grid-item-card:: -Second explanation + :octicon:`x-circle-fill` **Incorrect** -.. code-block:: + .. code-block:: - # Code block 2 + .. code-block:: + # This is a simple code block + from ansys.dpf import core as dpf - Every code implementation must be commented: @@ -347,9 +354,9 @@ Second explanation :padding: 2 :margin: 2 - .. grid-item:: + .. grid-item-card:: - **Correct** + :octicon:`check-circle-fill` **Correct** .. code-block:: @@ -358,34 +365,73 @@ Second explanation # Get the stress results stress_fc = model.results.stress.eval() - .. grid-item:: + .. grid-item-card:: - **Incorrect** + :octicon:`x-circle-fill` **Incorrect** .. code-block:: model = dpf.Model() stress_fc = model.results.stress.eval() -- When using a PyDPF-Core object or method you must use key arguments +- You must split your code in several parts so you can make explanations between them: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + First explanation + + .. code-block:: + + # Code comment 1 + code1 + + Second explanation + + .. code-block:: + + # Code comment 2 + code2 + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # First explanation + # Code comment 1 + code1 + + # Second explanation + # Code comment 2 + code2 + +- When using a PyDPF-Core object or method you must use key arguments: .. grid:: 2 :gutter: 2 :padding: 2 :margin: 2 - .. grid-item:: + .. grid-item-card:: - **Correct** + :octicon:`check-circle-fill` **Correct** .. code-block:: # Get the stress results stress_fc = model.results.stress(time_scoping=time_steps).eval() - .. grid-item:: + .. grid-item-card:: - **Incorrect** + :octicon:`x-circle-fill` **Incorrect** .. code-block:: @@ -395,9 +441,66 @@ Second explanation Text formating ~~~~~~~~~~~~~~ +- When enumerating something you must use bullet lists: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + This operator accepts as arguments: + + - A Result; + - An Operator; + - A FieldsContainer. + + .. grid-item-card:: + :octicon:`x-circle-fill` **Incorrect** + .. code-block:: + + This operator accepts a Result, an Operator or a + FieldsContainer as arguments. + +- If the enumeration represent a order of topics the list must be numbered: + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + To extract the mesh you need to follow those steps: + + #. Get the result file; + #. Create a Model; + #. Get the MeshedRegion. + + The ``#.`` renders as a numbered list. + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + To extract the mesh you need to follow those steps: + - Get the result file; + - Create a Model; + - Get the MeshedRegion. +- If you need to put code blocks between the list items first you enumerate and reference them in a list. Then, you + explore each of them separately in sub headings. From 8de7c926268e236b70fc15f42dd1302349362d95 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 3 Dec 2024 12:28:14 +0100 Subject: [PATCH 16/42] add tutorial_content_template.rst --- .../write_doc/tutorial_content_template.rst | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 doc/source/getting_started/write_doc/tutorial_content_template.rst diff --git a/doc/source/getting_started/write_doc/tutorial_content_template.rst b/doc/source/getting_started/write_doc/tutorial_content_template.rst new file mode 100644 index 00000000000..e0f0bea6cd2 --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_content_template.rst @@ -0,0 +1,96 @@ + +Tabs for different solvers +-------------------------- + +Here you have to make an implementation but it is different for the different solvers + +.. tab-set:: + + .. tab-item:: MAPDL + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: LSDYNA + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: Fluent + + Explanation ... + + .. jupyter-execute:: + + # Code block + + .. tab-item:: CFX + + Explanation ... + + .. jupyter-execute:: + + # Code block + +Bullet lists +------------ + +Here you enumerate something: + +- something 1; +- something 2; +- something 3. + +Here you enumerate something with a numbered list: + +#. something 1; +#. something 2; +#. something 3. + +Bullet lists with explanations between items +-------------------------------------------- + +Here you enumerate something and reference them to use each item as a subheading: + +- :ref:`Something 1`; +- :ref:`Something 2`; +- :ref:`Something 3`. + +.. _ref_something_1: + +Something 1 +^^^^^^^^^^^ + +Explanation 1 + +.. jupyter-execute:: + + # Code block 1 + +.. _ref_something_2: + +Something 2 +^^^^^^^^^^^ + +Explanation 2 + +.. jupyter-execute:: + + # Code block 2 + +.. _ref_something_3: + +Something 3 +^^^^^^^^^^^ + +Explanation 3 + +.. jupyter-execute:: + + # Code block 3 From 624993c701d81fa3b5fcd337e62e93df20becfaf Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 3 Dec 2024 12:28:23 +0100 Subject: [PATCH 17/42] add tutorial_structure_template.rst --- .../write_doc/tutorial_structure_template.rst | 41 +++++++++++++ .../write_doc/tutorial_template.rst | 59 ------------------- 2 files changed, 41 insertions(+), 59 deletions(-) create mode 100644 doc/source/getting_started/write_doc/tutorial_structure_template.rst delete mode 100644 doc/source/getting_started/write_doc/tutorial_template.rst diff --git a/doc/source/getting_started/write_doc/tutorial_structure_template.rst b/doc/source/getting_started/write_doc/tutorial_structure_template.rst new file mode 100644 index 00000000000..7d0d4a8e98b --- /dev/null +++ b/doc/source/getting_started/write_doc/tutorial_structure_template.rst @@ -0,0 +1,41 @@ +.. _ref_tutorial_template: + +============== +Tutorial title +============== + +.. include:: ../../../links_and_refs.rst +.. |Examples| replace:: :class:`ansys.dpf.core.examples` + +This sentence resumes the goal of the tutorial + +Introduction to the tutorial + +:jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` + +First Step +---------- + +First, you ... + +.. jupyter-execute:: + + # Code block 1 + +Second step +----------- + +Then, you ... + +.. jupyter-execute:: + + # Code block 2 + +Final Step +---------- + +Finally, you ... + +.. jupyter-execute:: + + # Code block 3 diff --git a/doc/source/getting_started/write_doc/tutorial_template.rst b/doc/source/getting_started/write_doc/tutorial_template.rst deleted file mode 100644 index f0f1a5879e2..00000000000 --- a/doc/source/getting_started/write_doc/tutorial_template.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _ref_tutorial_template: - -============== -Tutorial title -============== - -.. |Examples| replace:: :class:`ansys.dpf.core.examples` - -This sentence resumes the goal of the tutorial - -Introduction to the tutorial - -:jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` - -First Step ----------- - -Here you have to make an implementation but it is different for the different solvers - -.. tab-set:: - - .. tab-item:: MAPDL - - Explanation ... - - .. jupyter-execute:: - - # Code block - - .. tab-item:: LSDYNA - - Explanation ... - - .. jupyter-execute:: - - # Code block - - .. tab-item:: Fluent - - Explanation ... - - .. jupyter-execute:: - - # Code block - - .. tab-item:: CFX - - Explanation ... - - .. jupyter-execute:: - - # Code block - -Second step ------------ - -Final Step ----------- - From 9e43d18433d9282d89abdbacaadd0f29d0d14d71 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 3 Dec 2024 12:31:02 +0100 Subject: [PATCH 18/42] updates the guide_lines_tutorials.rst with the new tutorial templates refs --- .../getting_started/write_doc/guide_lines_tutorials.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index 4e08ad8a789..88d14e501a4 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -109,7 +109,8 @@ You must also add the ``index.rst`` file in the main user guide page toctree. Yo Adding a new tutorial ===================== -:download:`Download the tutorial card template` :download:`Download the tutorial template` +:download:`Download the tutorial card template` :download:`Download the tutorial structure template` +:download:`Download the tutorial content formating template` Location and naming ------------------- @@ -314,7 +315,7 @@ to have the code blocks in different tabs. You can see an example of this case i Code blocks ~~~~~~~~~~~ -The tutorials must have code blocks where you show how you actually implement the coode. +The tutorials must have code blocks where you show how you actually implement the code. The guidelines for the code snippets are: - Use the `jupyter sphinx`_ extension to show code blocks. Its executes embedded code in From 404a90f1bf004c83227fd2f929a3c6df6d3482a5 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 3 Dec 2024 14:22:52 +0100 Subject: [PATCH 19/42] updates the guide_lines_tutorials.rst --- .../write_doc/guide_lines_tutorials.rst | 29 +++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index 88d14e501a4..a69f1b51948 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -100,8 +100,30 @@ The new folder must contain at least a ``index.rst`` file. This file has: tutorial_file.rst -You must also add the ``index.rst`` file in the main user guide page toctree. You can find it at the end of -``doc/source/user_guide/index.rst`` file. +You must also add the new section ``index.rst`` file in the main user guide page toctree. You can find this toctree +at the end of ``doc/source/user_guide/index.rst`` file. + +.. code-block:: + + .. toctree:: + :maxdepth: 2 + :hidden: + :caption: Tutorials + + tutorials/data_structures/index.rst + tutorials/language_and_usage/index.rst + tutorials/post_processing_basics/index.rst + tutorials/import_data/index.rst + tutorials/mesh/index.rst + tutorials/transform_data/index.rst + tutorials/export_data/index.rst + tutorials/plot/index.rst + tutorials/animate/index.rst + tutorials/enriching_dpf_capabilities/index.rst + tutorials/distributed_files/index.rst + tutorials/dpf_server/index.rst + tutorials/licensing/index.rst + tutorials/new_section/index.rst .. _ref_guide_lines_add_new_tutorial: @@ -162,9 +184,6 @@ This first part is essential for clarity, organization and usability of the tuto purpose, making it easy to understand what is going to be explained and reference it within the other parts of the documentation. -Components -~~~~~~~~~~ - The preamble must have the following components: - File reference name; From 54103fec7fa4692ccc4f1ea1c2485ae12bfe067e Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Fri, 3 Jan 2025 15:53:30 +0100 Subject: [PATCH 20/42] delete file basic_tutorial.rst --- .../user_guide/tutorials/basic_tutorial.rst | 241 ------------------ 1 file changed, 241 deletions(-) delete mode 100644 doc/source/user_guide/tutorials/basic_tutorial.rst diff --git a/doc/source/user_guide/tutorials/basic_tutorial.rst b/doc/source/user_guide/tutorials/basic_tutorial.rst deleted file mode 100644 index 11b7097676d..00000000000 --- a/doc/source/user_guide/tutorials/basic_tutorial.rst +++ /dev/null @@ -1,241 +0,0 @@ -.. _ref_tutorials_basic: - -================== -The basic tutorial -================== - -This tutorial guides throughout the basic concepts and features of the PyDPF-Core tool. -It helps to have a Python interpreter for hands-on experience, but all code examples are -executed, so the tutorial can be read off-line as well. - -For a complete description of all the objects and modules, see the :ref:`API reference ` section. - -This page is divided in two sections: - -.. grid:: 1 1 2 2 - :gutter: 2 - :padding: 2 - :margin: 2 - - .. grid-item-card:: Overview - :link: tutorials_overview - :link-type: ref - :text-align: center - - Learn the different ways to interact with data by calling PyDPF-Core commands and operators. - - .. grid-item-card:: Postprocessing main steps - :link: tutorials_main_steps - :link-type: ref - :text-align: center - - How to do a basic prost-processing by transforming simulation data into output - data that can be used to visualize and analyze results - -.. _tutorials_overview: - -Overview --------- - - - -.. _tutorials_main_steps: - -Postprocessing main steps -------------------------- - -There are five main steps to transform simulation data into output data that can -be used to visualize and analyze simulation results: - -.. grid:: - :gutter: 2 - :padding: 2 - :margin: 2 - - .. grid-item-card:: 1 - :link: tutorials_main_steps_1 - :link-type: ref - :text-align: center - - Importing and opening results files - - .. grid-item-card:: 2 - :link: tutorials_main_steps_2 - :link-type: ref - :text-align: center - - Access and extract results - - .. grid-item-card:: 3 - :link: tutorials_main_steps_3 - :link-type: ref - :text-align: center - - Transform available data - - .. grid-item-card:: 4 - :link: tutorials_main_steps_4 - :link-type: ref - :text-align: center - - Visualize the data - - .. grid-item-card:: 5 - :link: tutorials_main_steps_5 - :link-type: ref - :text-align: center - - Extract data - -.. _tutorials_main_steps_1: - -1- Importing and opening results files -************************************** - -First, import the DPF-Core module as ``dpf`` and import the included examples file - -.. code-block:: python - - from ansys.dpf import core as dpf - from ansys.dpf.core import examples - from ansys.dpf.core import operators as ops - -`DataSources' is a class that manages paths to their files. Use this object to declare -data inputs for DPF and define their locations. - -.. code-block:: python - - # Define the DataSources object - my_data_sources = dpf.DataSources(result_path=examples.find_simple_bar()) - - -The model is a helper designed to give shortcuts to access the analysis results -metadata, by opening a DataSources or a Streams, and to instanciate results provider for it. - -Printing the model displays: - - - Analysis type - - Available results - - Size of the mesh - - Number of results - -.. code-block:: python - - # Define the Model object - my_model = dpf.Model(data_sources=my_data_sources) - print(my_model) - -.. rst-class:: sphx-glr-script-out - - .. jupyter-execute:: - :hide-code: - - from ansys.dpf import core as dpf - from ansys.dpf.core import examples - from ansys.dpf.core import operators as ops - my_data_sources = dpf.DataSources(result_path=examples.find_simple_bar()) - my_model = dpf.Model(data_sources=my_data_sources) - print(my_model) - -.. _tutorials_main_steps_2: - -2- Access and extract results -***************************** - -We see in the model that a displacement result is available. You can access this result by: - -.. code-block:: python - - # Define the displacement results through the models property `results` - my_displacements = my_model.results.displacement.eval() - print(my_displacements) - -.. rst-class:: sphx-glr-script-out - - .. jupyter-execute:: - :hide-code: - - my_displacements = my_model.results.displacement.eval() - print(my_displacements) - -The displacement data can be extract by: - -.. code-block:: python - - # Extract the data of the displacement field - my_displacements_0 = my_displacements[0].data - print(my_displacements_0) - -.. rst-class:: sphx-glr-script-out - - .. jupyter-execute:: - :hide-code: - - my_displacements_0 = my_displacements[0].data - print(my_displacements_0) - -.. _tutorials_main_steps_3: - -3- Transform available data -*************************** - -Several transformations can be made with the data. They can be a single operation, -by using only one operator, or they can represent a succession of operations, by defining a -workflow with chained operators. - -Here we star by computing the displacements norm. - -.. code-block:: python - - # Define the norm operator (here for a fields container) for the displacement - my_norm = ops.math.norm_fc(fields_container=my_displacements).eval() - print(my_norm[0].data) - -.. rst-class:: sphx-glr-script-out - - .. jupyter-execute:: - :hide-code: - - my_norm = ops.math.norm_fc(fields_container=my_displacements).eval() - print(my_norm[0].data) - -Then we compute the maximum values of the normalised displacement - -.. code-block:: python - - # Define the maximum operator and chain it to the norm operator - my_max= ops.min_max.min_max_fc(fields_container=my_norm).outputs.field_max() - print(my_max) - -.. rst-class:: sphx-glr-script-out - - .. jupyter-execute:: - :hide-code: - - my_max = ops.min_max.min_max_fc(fields_container=my_norm).outputs.field_max() - print(my_max) - -.. _tutorials_main_steps_4: - -4- Visualize the data -********************* - -Plot the transformed displacement results - -.. code-block:: python - - # Define the support of the plot (here we plot the displacement over the mesh) - my_model.metadata.meshed_region.plot(field_or_fields_container=my_displacements) - -.. rst-class:: sphx-glr-script-out - - .. jupyter-execute:: - :hide-code: - - my_model.metadata.meshed_region.plot(field_or_fields_container=my_displacements) - -.. _tutorials_main_steps_5: - -5- Extract the data -******************* - From 744f2109c752d4e59cded2be9fbee3fb315a0e5a Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Tue, 7 Jan 2025 10:19:14 +0100 Subject: [PATCH 21/42] Update doc/source/getting_started/write_doc/guide_lines_tutorials.rst --- doc/source/getting_started/write_doc/guide_lines_tutorials.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index a69f1b51948..6ef3b3c4ac4 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -212,7 +212,7 @@ The preamble must have the following components: Introduction to the tutorial - :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` + :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as Jupyter notebook` The main PyDPF-Core library references are available already defined in the ``doc/source/links_and_refs.rst`` file. To employ them, you use the ``include`` directive and use the substitution text as usual: From 388f48e781a76a7e0267491a36ef88585c72ef31 Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Tue, 7 Jan 2025 10:19:29 +0100 Subject: [PATCH 22/42] Update doc/source/getting_started/write_doc/tutorial_structure_template.rst --- .../getting_started/write_doc/tutorial_structure_template.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/getting_started/write_doc/tutorial_structure_template.rst b/doc/source/getting_started/write_doc/tutorial_structure_template.rst index 7d0d4a8e98b..ffcd2dd3574 100644 --- a/doc/source/getting_started/write_doc/tutorial_structure_template.rst +++ b/doc/source/getting_started/write_doc/tutorial_structure_template.rst @@ -11,7 +11,7 @@ This sentence resumes the goal of the tutorial Introduction to the tutorial -:jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as notebook` +:jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as Jupyter notebook` First Step ---------- From ce79f12ab7e1d0582e6a6182203f7b5359143439 Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Tue, 7 Jan 2025 11:25:00 +0100 Subject: [PATCH 23/42] Apply suggestions from code review Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- .../getting_started/write_code/index.rst | 2 +- .../write_doc/guide_lines_tutorials.rst | 86 ++++++++++--------- .../getting_started/write_doc/index.rst | 2 +- .../write_doc/tutorial_card_template.rst | 19 ++-- .../write_doc/tutorial_structure_template.rst | 6 +- 5 files changed, 55 insertions(+), 60 deletions(-) diff --git a/doc/source/getting_started/write_code/index.rst b/doc/source/getting_started/write_code/index.rst index 8de86c95b31..acf376209aa 100644 --- a/doc/source/getting_started/write_code/index.rst +++ b/doc/source/getting_started/write_code/index.rst @@ -16,7 +16,7 @@ on your local machine as per the following steps: Clone the repository -------------------- -Before cloning the PyMAPDL repository, you must install a version control system such as Git. +Before cloning the PyDPF-Core repository, you must install a version control system such as Git. Then, clone and install the latest version of PyDPF-Core in development mode (using ``pip`` with the ``-e`` development flag) by running this code: diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index 6ef3b3c4ac4..53841afdfda 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -1,15 +1,15 @@ -.. _ref_guide_lines_tutorials: +.. _ref_guidelines_tutorials: -============================ -Writing tutorials guidelines -============================ +================= +Writing tutorials +================= -You can improve the Py-DPF-Core documentation by adding a: +You can improve the PyDPF-Core documentation by adding a: -- :ref:`New tutorials section`; -- :ref:`New tutorial`. +- :ref:`New tutorials section`; +- :ref:`New tutorial`. -To do so, you must follow the guide lines presented here. +To do so, you must follow the guidelines presented here. You also need to understand the structure of the ``doc`` directory on the PyDPF-Core library: .. code-block:: @@ -28,9 +28,9 @@ You also need to understand the structure of the ``doc`` directory on the PyDPF- │ ├── make.bat -You will be handling only the ``doc/source/user_guide`` directory . +Tutorials are located in the ``doc/source/user_guide`` directory. -.. _ref_guide_lines_add_new_tutorial_section: +.. _ref_guidelines_add_new_tutorial_section: ============================= Adding a new tutorial section @@ -40,14 +40,15 @@ Adding a new tutorial section .. note:: - Avoid creating new folders unless it is absolutely necessary. If you are in doubt, its precise location can be - advised on the pull request. If you must create a new folder, make sure to add a ``index.rst`` file containing - a reference, a title and a description of the section. Otherwise the new folder will be ignored by Sphinx. + Avoid creating new folders unless absolutely necessary. + When in doubt, mention the location of the new section in the pull request for approval. + If you must create a new folder, make sure to add an ``index.rst`` file with a reference, a title, and a description of the section. + The documentation ignores folders lacking this file. Location and naming ------------------- -The new tutorial section must be organized in a new folder in ``doc/source/user_guide/tutorials/new_section_name``. +The new tutorial section must reside in a new folder such as ``doc/source/user_guide/tutorials/new_section_name``. .. code-block:: @@ -61,13 +62,13 @@ The new tutorial section must be organized in a new folder in ``doc/source/user_ Structure --------- -The new folder must contain at least a ``index.rst`` file. This file has: +The section folder must contain an ``index.rst`` file with: -- Reference name; -- Section title; -- General description of the content of the tutorials in this section; -- Cards with the tutorial title, description and applicable solvers (the card must have a link to the tutorial file); -- Toctree with the tutorials in the section. +- a reference tag for referencing this section in other parts of the documentation, +- a title for the tutorial section, +- a general description of the topics covered in the tutorials in this section, +- cards with links to the tutorials, titles, descriptions and applicable solvers, +- a ``Toctree`` for the tutorials in the section to appear in the navigation pane. .. code-block:: @@ -100,8 +101,9 @@ The new folder must contain at least a ``index.rst`` file. This file has: tutorial_file.rst -You must also add the new section ``index.rst`` file in the main user guide page toctree. You can find this toctree -at the end of ``doc/source/user_guide/index.rst`` file. +You must reference the new section ``index.rst`` file in the main user guide page toctree for it to appear in the sidebar of the user guide main page. You can find this toctree +at the end of the ``doc/source/user_guide/index.rst`` file. +For example: .. code-block:: @@ -125,7 +127,7 @@ at the end of ``doc/source/user_guide/index.rst`` file. tutorials/licensing/index.rst tutorials/new_section/index.rst -.. _ref_guide_lines_add_new_tutorial: +.. _ref_guidelines_add_new_tutorial: ===================== Adding a new tutorial @@ -137,7 +139,7 @@ Adding a new tutorial Location and naming ------------------- -New tutorials must be added as ``.rst`` files to: ``doc/source/user_guide/tutorials/section_name/tutorial_file.rst`` +New tutorials correspond to new ``.rst`` files in tutorial section folders, for example: ``doc/source/user_guide/tutorials/section/new_tutorial.rst`` .. code-block:: @@ -149,12 +151,12 @@ New tutorials must be added as ``.rst`` files to: ``doc/source/user_guide/tutori │ │ │ ├── section │ │ │ ├── new_tutorial.rst -You also have to add it to a card and the toctree on the tutorial section ``index.rst`` file. The card must have: +You must also add a new card in the ``index.rst`` file for the tutorial section as well as modify its toctree. The card must include: -- Tutorial title; -- Short description; -- Badges with the applicable solvers; -- Link to the tutorial file; +- a tutorial title, +- a short description, +- badges for the applicable solvers, +- a link (in this case, the reference tag) to the tutorial file. .. topic:: Card example @@ -170,28 +172,28 @@ You also have to add it to a card and the toctree on the tutorial section ``inde Structure --------- -The tutorial structure can be divided in two main parts: +The tutorial is divided in two main parts: -- :ref:`Preamble`; -- :ref:`Content`. +- :ref:`Preamble`; +- :ref:`Content`. -.. _ref_guide_lines_tutorial_preamble: +.. _ref_guidelines_tutorial_header: -Preamble +Header ^^^^^^^^ This first part is essential for clarity, organization and usability of the tutorial. It establishes the tutorials purpose, making it easy to understand what is going to be explained and reference it within the other parts of the documentation. -The preamble must have the following components: +The header must have : -- File reference name; -- Tutorial title; -- Substitution text for the PyDPF-Core library references that will be used across the tutorial; -- Short description (same phrase used in the tutorial card in the tutorial section ``index.rst`` file); -- Introduction that explains the context of the tutorial; -- Download script buttons; +- a reference tag, +- a tutorial title, +- any substitution text for references to the PyDPF-Core library used in the tutorial, +- a short description (same as for the tutorial card in the tutorial section), +- an introduction, +- download buttons for Python script and Jupyter notebook versions of the tutorial. .. code-block:: @@ -232,7 +234,7 @@ To employ them, you use the ``include`` directive and use the substitution text For more information on those references check the :download:`links and references file<../../links_and_refs.rst>`. -.. _ref_guide_lines_tutorial_content: +.. _ref_guidelines_tutorial_content: Content ^^^^^^^ diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index 6e882e94185..35792a708da 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -73,7 +73,7 @@ Each section has their own guidelines that must be followed when creating new co :margin: 2 .. grid-item-card:: **TUTORIALS** - :link: ref_guide_lines_tutorials + :link: ref_guidelines_tutorials :link-type: ref :class-title: sd-text-center sd-bg-light :class-header: sd-text-center diff --git a/doc/source/getting_started/write_doc/tutorial_card_template.rst b/doc/source/getting_started/write_doc/tutorial_card_template.rst index 05a77257c88..646a9e98c88 100644 --- a/doc/source/getting_started/write_doc/tutorial_card_template.rst +++ b/doc/source/getting_started/write_doc/tutorial_card_template.rst @@ -1,14 +1,9 @@ -.. grid:: 1 1 3 3 - :gutter: 2 - :padding: 2 - :margin: 2 +.. grid-item-card:: Tutorial title + :link: ref + :link-type: ref + :text-align: center - .. grid-item-card:: Tutorial title - :link: ref - :link-type: ref - :text-align: center + This tutorial ... - This tutorial ... - - +++ - :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` \ No newline at end of file + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` \ No newline at end of file diff --git a/doc/source/getting_started/write_doc/tutorial_structure_template.rst b/doc/source/getting_started/write_doc/tutorial_structure_template.rst index ffcd2dd3574..c933e42c6ba 100644 --- a/doc/source/getting_started/write_doc/tutorial_structure_template.rst +++ b/doc/source/getting_started/write_doc/tutorial_structure_template.rst @@ -4,12 +4,10 @@ Tutorial title ============== -.. include:: ../../../links_and_refs.rst -.. |Examples| replace:: :class:`ansys.dpf.core.examples` -This sentence resumes the goal of the tutorial +A single sentence describing the goal of the tutorial, which must match the one on the tutorial card in the section page -Introduction to the tutorial +Introduction to the tutorial. Here, you provide the necessary context or foundational information for understanding the tutorial. :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as Jupyter notebook` From 43bed3ee14cb5b123d31dad509db6361a16589a2 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 7 Jan 2025 11:46:00 +0100 Subject: [PATCH 24/42] updates the links references in the rst files --- doc/source/getting_started/contributing.rst | 6 +++--- doc/source/getting_started/write_code/index.rst | 2 +- doc/source/getting_started/write_doc/index.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/getting_started/contributing.rst b/doc/source/getting_started/contributing.rst index 1fffb4dfe95..72e1bc3e9cb 100644 --- a/doc/source/getting_started/contributing.rst +++ b/doc/source/getting_started/contributing.rst @@ -12,7 +12,7 @@ There are several ways to contribute to PyDPF-Core: - :ref:`ref_contributing_improve_doc` Overall guidance on contributing to a PyAnsys repository appears in -`Contributing `_ in the *PyAnsys Developer's Guide*. +`Contributing `_ in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar with this guide before attempting to contribute to PyDPF-Core. @@ -30,7 +30,7 @@ facing similar issues, making the repository more welcoming and inclusive. By pr 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 `PyDPF-Core Discussions page `_. +To discover how you can help see the `PyDPF-Core Discussions page `_. .. _ref_contributing_post_issues: @@ -44,7 +44,7 @@ project’s community, learn from others, and gain experience in issue tracking 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. -Use the `PyDPF-Core Issues page `_ to submit questions, report bugs, and request new features. When possible, use +Use the `PyDPF-Core 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; diff --git a/doc/source/getting_started/write_code/index.rst b/doc/source/getting_started/write_code/index.rst index acf376209aa..240f0f5abea 100644 --- a/doc/source/getting_started/write_code/index.rst +++ b/doc/source/getting_started/write_code/index.rst @@ -78,7 +78,7 @@ Here are the main guidelines for developing code in a repository: 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. + 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 diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index 35792a708da..dbc25fd903d 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -25,7 +25,7 @@ Here's a short summary of how to write good documentation: #. **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. + `numpydoc `_ convention for documenting code. #. **Tutorials and guides**: Create tutorials or guides to help users achieve specific tasks or workflows with PyDPF-Core. From 4c1477759fe3c0d313df115fbf42c89643c95043 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 7 Jan 2025 14:29:35 +0100 Subject: [PATCH 25/42] updates the links references in the install.rst file --- doc/source/getting_started/install.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/getting_started/install.rst b/doc/source/getting_started/install.rst index 3e14ed4543a..2abc71fb144 100644 --- a/doc/source/getting_started/install.rst +++ b/doc/source/getting_started/install.rst @@ -7,7 +7,7 @@ Installation Install using ``pip`` --------------------- -The standard package installer for Python is `pip `_. +The standard package installer for Python is `pip `_. To use PyDPF-Core with Ansys 2022 R2 or later, install the latest version with this command: @@ -16,7 +16,7 @@ with this command: pip install ansys-dpf-core -PyDPF-Core plotting capabilities require to have `PyVista `_ installed. +PyDPF-Core plotting capabilities require to have `PyVista `_ installed. To install PyDPF-Core with its optional plotting functionalities, use: .. code:: @@ -52,7 +52,7 @@ Install without internet If you are unable to install PyDPF-Core on the host machine using ``pip`` due to network isolation, download the wheelhouse corresponding to your platform and Python interpreter version -for the latest release of PyDPF-Core from the assets section of the `latest PyDPF-Core release on GitHub `_. +for the latest release of PyDPF-Core from the assets section of the `latest PyDPF-Core release on GitHub `_. The wheelhouse is a ZIP file containing Python wheels for all the packages PyDPF-Core requires to run. To install PyDPF-Core using the downloaded wheelhouse, unzip the wheelhouse to a local directory, @@ -64,8 +64,8 @@ then use the following command from within this local directory: Beware that PyDPF-Core wheelhouses do not include the optional plotting dependencies. To allow for plotting capabilities, also download the wheels corresponding to your platform and Python interpreter version -for `PyVista `_ and -`matplotlib `_, then place them in the same previous local directory and run the command above. +for `PyVista `_ and +`matplotlib `_, then place them in the same previous local directory and run the command above. Install in development mode From 03666da04ede5655d3ce6bd6b03c76a51cbf4330 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 7 Jan 2025 14:41:39 +0100 Subject: [PATCH 26/42] redirect to the PyAnsys guidelines for developing code and add the installation explanation before cloning --- .../getting_started/write_code/index.rst | 82 +++++++------------ 1 file changed, 29 insertions(+), 53 deletions(-) diff --git a/doc/source/getting_started/write_code/index.rst b/doc/source/getting_started/write_code/index.rst index 240f0f5abea..3a3e702d35c 100644 --- a/doc/source/getting_started/write_code/index.rst +++ b/doc/source/getting_started/write_code/index.rst @@ -7,10 +7,34 @@ Develop code You can help improve PyDPF-Core by fixing a bug. To do it, you must set up the repository on your local machine as per the following steps: +- :ref:`ref_write_code_install` - :ref:`ref_write_code_clone` - :ref:`ref_write_code_check_install` - :ref:`ref_write_code_develop_code` +.. _ref_write_code_install: + +Install the repository +---------------------- + +Install the PyDPF-Core repository. The standard package installer for Python is `pip `_. + +To use PyDPF-Core with Ansys 2022 R2 or later, install the latest version +with this command: + +.. code:: + + pip install ansys-dpf-core + +PyDPF-Core plotting capabilities require to have `PyVista `_ installed. +To install PyDPF-Core with its optional plotting functionalities, use: + +.. code:: + + pip install ansys-dpf-core[plotting] + +For more information about installing PyDPF-Core, see :ref:`installation`. + .. _ref_write_code_clone: Clone the repository @@ -18,7 +42,7 @@ Clone the repository Before cloning the PyDPF-Core repository, you must install a version control system such as Git. -Then, clone and install the latest version of PyDPF-Core in development mode (using ``pip`` with the ``-e`` +Then, clone the latest version of PyDPF-Core in development mode (using ``pip`` with the ``-e`` development flag) by running this code: .. code:: @@ -46,56 +70,8 @@ Run the following Python code to verify your PyDPF-Core installation: Develop the PyDPF-Core code --------------------------- -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. For example, the branch name must start with a prefix and a backslash. - -#. **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. - Pull requests must follow the same convention as the commit messages. - - The pull requests can also be labeled for easier repository maintenance. - Those labels are already defined in the repository. - -#. **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. - -#. **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/pydpf-admins`` in a comment - so they they are notified. +Overall guidance on contributing to the code of a PyAnsys repository appears in +`Contributing `_ in the *PyAnsys Developer's Guide*. -By following these guidelines, you can ensure smooth and organized code -development within a repository, fostering collaboration, code quality, and feature enhancement. \ No newline at end of file +You must also follow the `Coding style `_ guide to ensure +that all source code looks the same across the project. \ No newline at end of file From 6432bffaceaaf0e4ede85df64c4e026940cd6eec Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 7 Jan 2025 14:50:42 +0100 Subject: [PATCH 27/42] redirect to the PyAnsys guidelines for developing documentation --- .../getting_started/write_doc/index.rst | 39 +++---------------- 1 file changed, 5 insertions(+), 34 deletions(-) diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index dbc25fd903d..97eaec985ab 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -4,41 +4,11 @@ Documentation ============= -Writing good documentation for a GitHub repository is crucial to ensure that -users and contributors can understand, use, and contribute to PyDPF-Core -effectively. +Overall guidance on contributing to the documentation a PyAnsys repository appears in +`Documenting `_ in the *PyAnsys Developer's Guide*. -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. - -#. **Use Sphinx properly**: Sphinx has multiple features and directives. Before - starting to write documentation, you should get familiar with it. For guidance, - see these Sphinx and DocUtils topics: `Directives `_, - `reStructuredText Primer `_ and - `reStructuredText Directives `_. - -#. **Usage Examples**: Include real-world usage examples, code snippets, and - explanations to demonstrate how users can make the most of PyDPF-Core. - -#. **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 PyDPF-Core. - -#. **Troubleshooting**: Anticipate common issues and provide solutions - in a troubleshooting section. - -#. **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. +You must also follow the `Documentation style `_ guide to +ensure that all the documentation looks the same across the project. To improve the documentation you need to: @@ -48,6 +18,7 @@ To improve the documentation you need to: Clone the repository -------------------- + Clone and install the latest version of PyDPF-Core in development mode by running this code: From 8c75f84be7bda68b3fc95180fb72e55adcc762a7 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 7 Jan 2025 14:50:52 +0100 Subject: [PATCH 28/42] add new links and substitution text to the links_and_refs.rst file --- doc/source/links_and_refs.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/source/links_and_refs.rst b/doc/source/links_and_refs.rst index 2257acdcd4f..571bd1f739e 100644 --- a/doc/source/links_and_refs.rst +++ b/doc/source/links_and_refs.rst @@ -5,6 +5,7 @@ .. PyDPF-Core .. _pydpfcore_issues: https://github.com/ansys/pydpf-core/issues .. _pydpfcore_discussions: https://github.com/ansys/pydpf-core/discussions +.. _pydpfcore_latest_release: https://github.com/ansys/pydpf-core/releases/latest .. Pyansys .. _pyansys: https://docs.pyansys.com/version/dev/ @@ -16,10 +17,13 @@ .. _dev_guide_setup_your_environment: https://dev.docs.pyansys.com/how-to/setting-up.html .. _dev_guide_branch_names: https://dev.docs.pyansys.com/how-to/contributing.html#branch-naming-conventions .. _dev_guide_commit_names: https://dev.docs.pyansys.com/how-to/contributing.html#commit-naming-conventions +.. _dev_guide_doc_style: https://dev.docs.pyansys.com/doc-style/index.html +.. _dev_guide_documenting: https://dev.docs.pyansys.com/how-to/documenting.html# .. Other libraries documentations .. _pyvista_docs: https://docs.pyvista.org/version/stable/ .. _pyvista_doc_plot_method: https://docs.pyvista.org/api/plotting/_autosummary/pyvista.plot.html#pyvista.plot +.. _pyvista_org: https://pyvista.org/ .. _jupyter: https://jupyter.org/ .. _numpy_org: https://numpy.org/ .. _numpy_docs: https://numpy.org/doc/stable/ @@ -30,9 +34,13 @@ .. External links .. _sphinx: https://www.sphinx-doc.org/en/master/ .. _sphinx_directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html +.. _sphinx_basics: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _vale: https://www.vale.sh .. _docutils_directives: https://docutils.sourceforge.io/docs/ref/rst/directives.html .. _numpy_sphinx_ext_doc: https://numpydoc.readthedocs.io/en/latest/ +.. _pip_pypi_page: https://pypi.org/project/pip/ +.. _pyvista_download_files: https://pypi.org/project/pyvista/#files +.. _matplotlib_download_files: https://pypi.org/project/matplotlib/#files .. REFERENCES From 3a3f5f81477283b88aaf5023aa005f5cee2406e1 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Tue, 7 Jan 2025 15:16:32 +0100 Subject: [PATCH 29/42] update text in index.rst (write doc) --- doc/source/getting_started/write_doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index 97eaec985ab..337cf17ff13 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -4,7 +4,7 @@ Documentation ============= -Overall guidance on contributing to the documentation a PyAnsys repository appears in +Overall guidance on contributing to the documentation of a PyAnsys repository appears in `Documenting `_ in the *PyAnsys Developer's Guide*. You must also follow the `Documentation style `_ guide to From db567984d745bc194f14468927795a9a8113799f Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 8 Jan 2025 14:01:07 +0100 Subject: [PATCH 30/42] update the guide_lines_tutorials.rst --- .../write_doc/guide_lines_tutorials.rst | 324 +++++++++++++----- 1 file changed, 244 insertions(+), 80 deletions(-) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst index 53841afdfda..b28191685ef 100644 --- a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guide_lines_tutorials.rst @@ -10,6 +10,7 @@ You can improve the PyDPF-Core documentation by adding a: - :ref:`New tutorial`. To do so, you must follow the guidelines presented here. + You also need to understand the structure of the ``doc`` directory on the PyDPF-Core library: .. code-block:: @@ -70,38 +71,10 @@ The section folder must contain an ``index.rst`` file with: - cards with links to the tutorials, titles, descriptions and applicable solvers, - a ``Toctree`` for the tutorials in the section to appear in the navigation pane. -.. code-block:: - - .. _ref_tutorial_new_section_template: - - ============= - Section title - ============= - - These tutorials demonstrate how to ... - - .. grid:: 1 1 3 3 - :gutter: 2 - :padding: 2 - :margin: 2 - - .. grid-item-card:: Tutorial title - :link: ref - :link-type: ref - :text-align: center - - This tutorial ... - - +++ - :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` - - .. toctree:: - :maxdepth: 2 - :hidden: - - tutorial_file.rst +.. literalinclude:: tutorial_section_template.rst -You must reference the new section ``index.rst`` file in the main user guide page toctree for it to appear in the sidebar of the user guide main page. You can find this toctree +You must reference the new section ``index.rst`` file in the main user guide page toctree +for it to appear in the sidebar of the user guide main page. You can find this toctree at the end of the ``doc/source/user_guide/index.rst`` file. For example: @@ -112,19 +85,9 @@ For example: :hidden: :caption: Tutorials - tutorials/data_structures/index.rst - tutorials/language_and_usage/index.rst - tutorials/post_processing_basics/index.rst - tutorials/import_data/index.rst - tutorials/mesh/index.rst - tutorials/transform_data/index.rst - tutorials/export_data/index.rst - tutorials/plot/index.rst - tutorials/animate/index.rst - tutorials/enriching_dpf_capabilities/index.rst - tutorials/distributed_files/index.rst - tutorials/dpf_server/index.rst - tutorials/licensing/index.rst + tutorials/section_x/index.rst + tutorials/section_y/index.rst + tutorials/section_z/index.rst tutorials/new_section/index.rst .. _ref_guidelines_add_new_tutorial: @@ -133,13 +96,15 @@ For example: Adding a new tutorial ===================== -:download:`Download the tutorial card template` :download:`Download the tutorial structure template` +:download:`Download the tutorial card template` +:download:`Download the tutorial structure template` :download:`Download the tutorial content formating template` Location and naming ------------------- -New tutorials correspond to new ``.rst`` files in tutorial section folders, for example: ``doc/source/user_guide/tutorials/section/new_tutorial.rst`` +New tutorials correspond to new ``.rst`` files in tutorial section folders, +for example: ``doc/source/user_guide/tutorials/section/new_tutorial.rst`` .. code-block:: @@ -151,7 +116,8 @@ New tutorials correspond to new ``.rst`` files in tutorial section folders, for │ │ │ ├── section │ │ │ ├── new_tutorial.rst -You must also add a new card in the ``index.rst`` file for the tutorial section as well as modify its toctree. The card must include: +You must also add a new card in the ``index.rst`` file for the tutorial section as well as modify +its toctree. The card must include: - a tutorial title, - a short description, @@ -174,13 +140,13 @@ Structure The tutorial is divided in two main parts: -- :ref:`Preamble`; -- :ref:`Content`. +- :ref:`Preamble` +- :ref:`Content` .. _ref_guidelines_tutorial_header: Header -^^^^^^^^ +^^^^^^ This first part is essential for clarity, organization and usability of the tutorial. It establishes the tutorials purpose, making it easy to understand what is going to be explained and reference it within the other parts of @@ -195,29 +161,11 @@ The header must have : - an introduction, - download buttons for Python script and Jupyter notebook versions of the tutorial. -.. code-block:: - - .. _ref_tutorial_template: - - - ============== - Tutorial title - ============== - - - .. |Examples| replace:: :class:`ansys.dpf.core.examples` - - - This sentence resumes the goal of the tutorial - - - Introduction to the tutorial - - - :jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as Jupyter notebook` +.. literalinclude:: tutorial_structure_template.rst + :end-before: First Step The main PyDPF-Core library references are available already defined in the ``doc/source/links_and_refs.rst`` file. -To employ them, you use the ``include`` directive and use the substitution text as usual: +To employ them, you just need to use the substitution text as usual: .. code-block:: @@ -228,11 +176,10 @@ To employ them, you use the ``include`` directive and use the substitution text Tutorial title ============== - .. include:: ../../../links_and_refs.rst - Here some text. Here we use the |MeshedRegion| substitution text -For more information on those references check the :download:`links and references file<../../links_and_refs.rst>`. +For more information about the predefined references, see the +:download:`links and references file <../../links_and_refs.rst>`. .. _ref_guidelines_tutorial_content: @@ -337,9 +284,10 @@ Code blocks ~~~~~~~~~~~ The tutorials must have code blocks where you show how you actually implement the code. -The guidelines for the code snippets are: +In addition to the guidelines presented here, you must also follow the `Coding style `_ +guide to ensure that all code looks the same across the project. -- Use the `jupyter sphinx`_ extension to show code blocks. Its executes embedded code in +- Use the `jupyter sphinx `_ extension to show code blocks. It executes embedded code in a Jupyter kernel and embeds outputs of that code in the document: .. grid:: 2 @@ -384,6 +332,7 @@ The guidelines for the code snippets are: # Define the model model = dpf.Model() + # Get the stress results stress_fc = model.results.stress.eval() @@ -460,9 +409,152 @@ The guidelines for the code snippets are: # Get the stress results stress_fc = model.results.stress(time_steps).eval() +- When quoting APIs in the code comments you must always use their scripting name. Mind the use of + a capital letter to name the DPF objects + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Define the DataSources object + ds = dpf.DataSources() + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # Define the data sources object + ds = dpf.DataSources() + + .. code-block:: + + # Define the Data Sources object + ds = dpf.DataSources() + +- Use blank lines between code lines for better clarity. + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Define the result file path + result_file_path_1 = '/tmp/file.rst' + + # Define the DataSources object + ds_1 = dpf.DataSources(result_path=result_file_path_1) + + # Create a Model + model_1 = dpf.Model(data_sources=ds_1) + + # Get the stress results + stress_fc = model_1.results.stress.eval() + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # Define the result file path + result_file_path_1 = '/tmp/file.rst' + # Define the DataSources object + ds_1 = dpf.DataSources(result_path=result_file_path_1) + # Create a Model + model_1 = dpf.Model(data_sources=ds_1) + # Get the stress results + stress_fc = model_1.results.stress.eval() + +- Avoid naming the variables with the same name as an argument or an API. You can get inspirations from the + tutorials available at :ref:`ref_tutorials`. + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + # Define the result file path + result_file_path = '/tmp/file.rst' + + # Define the DataSources object + ds = dpf.DataSources(result_path=result_file_path) + + # Create a Model + my_model = dpf.Model(data_sources=ds) + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + # Define the result file path + result_path = '/tmp/file.rst' + + # Define the DataSources object + data_sources = dpf.DataSources(result_path=result_path) + + # Create a Model + model = dpf.Model(data_sources=data_sources) + Text formating ~~~~~~~~~~~~~~ +In addition to the guidelines presented here, you must also follow the `Documentation style `_ +guide to ensure that all the tutorials looks the same across the project. + +- When quoting APIs in the text you must always use a reference to redirect it to the API reference + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + Here we use the |MeshedRegion| substitution text + + **Rendered text:** + + Here some text. Here we use the |MeshedRegion| substitution text + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + Here we don't use the MeshedRegion substitution text + + **Rendered text:** + + Here some text. Here we don't use the MeshedRegion substitution text + - When enumerating something you must use bullet lists: .. grid:: 2 @@ -478,9 +570,9 @@ Text formating This operator accepts as arguments: - - A Result; - - An Operator; - - A FieldsContainer. + - A Result + - An Operator + - A FieldsContainer .. grid-item-card:: @@ -524,5 +616,77 @@ Text formating - Create a Model; - Get the MeshedRegion. -- If you need to put code blocks between the list items first you enumerate and reference them in a list. Then, you +- If you need to develop explanations for each item of the list, first, you enumerate and reference them. Then, you explore each of them separately in sub headings. + +.. grid:: 2 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: + + :octicon:`check-circle-fill` **Correct** + + .. code-block:: + + Section title + ------------- + + Here, we explain the two following items: + + - :ref:`Item 1 ` + - :ref:`Content` + + + .. _ref_tutorial_name_item_1: + + Item 1 + ^^^^^^ + + Development text and code blocks 1 ... + + + .. _ref_tutorial_name_item_2: + + Item 2 + ^^^^^^ + + Development text and code blocks 2 ... + + .. grid-item-card:: + + :octicon:`x-circle-fill` **Incorrect** + + .. code-block:: + + Section title + ------------- + + Here, we explain the two following items: + + - Item 1 + - Item 2 + + Item 1 + ^^^^^^ + Development text and code blocks 1 ... + + Item 2 + ^^^^^^ + Development text and code blocks 2 ... + + + .. code-block:: + + Section title + ------------- + + Here, we explain the two following items: + + - Item 1 + Development text and code blocks 1 ... + + + - Item 2 + Development text and code blocks 2 ... From bae3156d5b1c644aacdb9f7bf89e9a59cf12b209 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 8 Jan 2025 14:01:25 +0100 Subject: [PATCH 31/42] update the tutorial_structure_template.rst --- .../write_doc/tutorial_structure_template.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/source/getting_started/write_doc/tutorial_structure_template.rst b/doc/source/getting_started/write_doc/tutorial_structure_template.rst index c933e42c6ba..8b7536c1cb1 100644 --- a/doc/source/getting_started/write_doc/tutorial_structure_template.rst +++ b/doc/source/getting_started/write_doc/tutorial_structure_template.rst @@ -4,12 +4,14 @@ Tutorial title ============== +.. |displacement_op| replace:: :class:`ansys.dpf.core.operators.result.displacement.displacement` -A single sentence describing the goal of the tutorial, which must match the one on the tutorial card in the section page +A single sentence describing the goal of the tutorial, which must match the one on the tutorial card in the section page. Introduction to the tutorial. Here, you provide the necessary context or foundational information for understanding the tutorial. -:jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as Jupyter notebook` +:jupyter-download-script:`Download tutorial as Python script` +:jupyter-download-notebook:`Download tutorial as Jupyter notebook` First Step ---------- From c09b799af06a07ef6a1524b01456c794c35741c1 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 8 Jan 2025 14:16:02 +0100 Subject: [PATCH 32/42] add the installing dpf server explanation to the write code index.rst --- .../getting_started/write_code/index.rst | 22 +++---------------- 1 file changed, 3 insertions(+), 19 deletions(-) diff --git a/doc/source/getting_started/write_code/index.rst b/doc/source/getting_started/write_code/index.rst index 3a3e702d35c..3a2be65a400 100644 --- a/doc/source/getting_started/write_code/index.rst +++ b/doc/source/getting_started/write_code/index.rst @@ -14,26 +14,10 @@ on your local machine as per the following steps: .. _ref_write_code_install: -Install the repository ----------------------- - -Install the PyDPF-Core repository. The standard package installer for Python is `pip `_. - -To use PyDPF-Core with Ansys 2022 R2 or later, install the latest version -with this command: - -.. code:: - - pip install ansys-dpf-core - -PyDPF-Core plotting capabilities require to have `PyVista `_ installed. -To install PyDPF-Core with its optional plotting functionalities, use: - -.. code:: - - pip install ansys-dpf-core[plotting] +Install the repository and the DPF server +----------------------------------------- -For more information about installing PyDPF-Core, see :ref:`installation`. +Install the PyDPF-Core repository by following the steps in :ref:`installation` and :ref:`ref_dpf_server`. .. _ref_write_code_clone: From a498138a4289281e8fbc4e5166eea672046f6b71 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 8 Jan 2025 14:16:35 +0100 Subject: [PATCH 33/42] add the link to the jupyter execute extension doc to the links_and_refs.rst file --- doc/source/links_and_refs.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/links_and_refs.rst b/doc/source/links_and_refs.rst index 571bd1f739e..94d4218bcf4 100644 --- a/doc/source/links_and_refs.rst +++ b/doc/source/links_and_refs.rst @@ -27,6 +27,7 @@ .. _jupyter: https://jupyter.org/ .. _numpy_org: https://numpy.org/ .. _numpy_docs: https://numpy.org/doc/stable/ +.. _jupyter_sphinx_ext: https://jupyter-sphinx.readthedocs.io/en/latest/ .. Other libraries repos .. _pyvista_github : https://github.com/pyvista/pyvista From da323b544af89d07ba8189fdc163a8a840462e1a Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 8 Jan 2025 14:18:06 +0100 Subject: [PATCH 34/42] rename the guidelines_tutorials.rst file --- .../{guide_lines_tutorials.rst => guidelines_tutorials.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/source/getting_started/write_doc/{guide_lines_tutorials.rst => guidelines_tutorials.rst} (100%) diff --git a/doc/source/getting_started/write_doc/guide_lines_tutorials.rst b/doc/source/getting_started/write_doc/guidelines_tutorials.rst similarity index 100% rename from doc/source/getting_started/write_doc/guide_lines_tutorials.rst rename to doc/source/getting_started/write_doc/guidelines_tutorials.rst From 33f763fdb4998f6efdb3000ce6afcd1a8b045735 Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Wed, 8 Jan 2025 14:30:40 +0100 Subject: [PATCH 35/42] updates the guidelines_tutorials.rst name in the toctree of the write doc index.rst --- doc/source/getting_started/write_doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index 337cf17ff13..c9f1cdd7e37 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -135,4 +135,4 @@ released versions. :maxdepth: 2 :hidden: - guide_lines_tutorials.rst + guidelines_tutorials.rst From e31207b01ef7afba78e686d051d71d2dbebdae04 Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Tue, 14 Jan 2025 16:47:58 +0100 Subject: [PATCH 36/42] Apply suggestions from code review Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- .../write_doc/guidelines_tutorials.rst | 57 +++++++++---------- .../getting_started/write_doc/index.rst | 6 +- 2 files changed, 31 insertions(+), 32 deletions(-) diff --git a/doc/source/getting_started/write_doc/guidelines_tutorials.rst b/doc/source/getting_started/write_doc/guidelines_tutorials.rst index b28191685ef..00529bbc3f8 100644 --- a/doc/source/getting_started/write_doc/guidelines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guidelines_tutorials.rst @@ -164,8 +164,8 @@ The header must have : .. literalinclude:: tutorial_structure_template.rst :end-before: First Step -The main PyDPF-Core library references are available already defined in the ``doc/source/links_and_refs.rst`` file. -To employ them, you just need to use the substitution text as usual: +The main PyDPF-Core library references are available in the ``doc/source/links_and_refs.rst`` file. +To add a reference, use the substitution text as usual: .. code-block:: @@ -186,7 +186,7 @@ For more information about the predefined references, see the Content ^^^^^^^ -A tutorial goal is to explain how to perform a task step by step and understand the underlying concepts. +The goal of a tutorial is to present a feature or explain how to perform a common task step by step while explaining a behavior or underlying concepts. Thus, its structure must prioritize clarity, simplicity, and logical flow. Sections @@ -196,15 +196,15 @@ A well-organized tutorial breaks down complex tasks into manageable steps, prese to avoid overwhelming the user. It combines concise explanations with actionable instructions, ensuring users can follow along easily while building their understanding. -Thus, the sections of the content are the steps themselves. Globally those steps looks like: +Thus, the sections of the content are the steps themselves. These steps are generally similar to: -#. Get data, define DPF objects that contains the data; -#. One or more steps where you manipulate, handles the data/ DPF objects; -#. Conclusion, here is the final step where the tutorial goal is accomplished. +#. A first step where you get some data and create DPF objects based on the data; +#. One or more steps where you manipulate the data or the DPF objects; +#. A final step where you reach the objective of the tutorial and obtain the expected result. For example: -A tutorial goal is to explains how to plot a mesh using PyDPF-Core. +A tutorial explains how to plot a mesh using PyDPF-Core. The steps to achieve this task are: #. Import a result file; @@ -235,8 +235,7 @@ To create those section, underline it with the appropriate characters (here: ``- Tabs ~~~~ -You must use tabs in the case the tutorial is applicable fore more then one solver and the implementations are -different for each of them. +You must use tabs when a step requires a solver-specific implementation. These tabs looks like: @@ -317,7 +316,7 @@ guide to ensure that all code looks the same across the project. # This is a simple code block from ansys.dpf import core as dpf -- Every code implementation must be commented: +- Use comments within a code block to clarify the purpose of a line: .. grid:: 2 :gutter: 2 @@ -345,7 +344,7 @@ guide to ensure that all code looks the same across the project. model = dpf.Model() stress_fc = model.results.stress.eval() -- You must split your code in several parts so you can make explanations between them: +- Split your code in several parts to include longer explanations in text format or force showing an intermediate code output: .. grid:: 2 :gutter: 2 @@ -384,7 +383,7 @@ guide to ensure that all code looks the same across the project. # Code comment 2 code2 -- When using a PyDPF-Core object or method you must use key arguments: +- When using a PyDPF-Core object or method you must name arguments: .. grid:: 2 :gutter: 2 @@ -522,7 +521,7 @@ Text formating ~~~~~~~~~~~~~~ In addition to the guidelines presented here, you must also follow the `Documentation style `_ -guide to ensure that all the tutorials looks the same across the project. +guide to ensure that the tutorials follow a coherent writing style across the project. - When quoting APIs in the text you must always use a reference to redirect it to the API reference @@ -541,7 +540,7 @@ guide to ensure that all the tutorials looks the same across the project. **Rendered text:** - Here some text. Here we use the |MeshedRegion| substitution text + Here is some text. Here we use the |MeshedRegion| substitution text .. grid-item-card:: @@ -549,13 +548,13 @@ guide to ensure that all the tutorials looks the same across the project. .. code-block:: - Here we don't use the MeshedRegion substitution text + Here we do not use the MeshedRegion substitution text **Rendered text:** - Here some text. Here we don't use the MeshedRegion substitution text + Here is some text. Here we do not use the MeshedRegion substitution text -- When enumerating something you must use bullet lists: +- Use bullet lists when enumerating items: .. grid:: 2 :gutter: 2 @@ -583,7 +582,7 @@ guide to ensure that all the tutorials looks the same across the project. This operator accepts a Result, an Operator or a FieldsContainer as arguments. -- If the enumeration represent a order of topics the list must be numbered: +- Use a numbered list for ordered items: .. grid:: 2 :gutter: 2 @@ -616,7 +615,7 @@ guide to ensure that all the tutorials looks the same across the project. - Create a Model; - Get the MeshedRegion. -- If you need to develop explanations for each item of the list, first, you enumerate and reference them. Then, you +- If you need to develop explanations for each item of the list, first, enumerate and reference them. Then, explore each of them separately in sub headings. .. grid:: 2 @@ -633,7 +632,7 @@ guide to ensure that all the tutorials looks the same across the project. Section title ------------- - Here, we explain the two following items: + This section presents two items: - :ref:`Item 1 ` - :ref:`Content` @@ -644,7 +643,7 @@ guide to ensure that all the tutorials looks the same across the project. Item 1 ^^^^^^ - Development text and code blocks 1 ... + Presentation of the first item... .. _ref_tutorial_name_item_2: @@ -652,7 +651,7 @@ guide to ensure that all the tutorials looks the same across the project. Item 2 ^^^^^^ - Development text and code blocks 2 ... + Presentation of the second item... .. grid-item-card:: @@ -663,18 +662,18 @@ guide to ensure that all the tutorials looks the same across the project. Section title ------------- - Here, we explain the two following items: + This section presents two items: - Item 1 - Item 2 Item 1 ^^^^^^ - Development text and code blocks 1 ... + Presentation of the first item... Item 2 ^^^^^^ - Development text and code blocks 2 ... + Presentation of the second item... .. code-block:: @@ -682,11 +681,11 @@ guide to ensure that all the tutorials looks the same across the project. Section title ------------- - Here, we explain the two following items: + This section presents two items: - Item 1 - Development text and code blocks 1 ... + Presentation of the first item... - Item 2 - Development text and code blocks 2 ... + Presentation of the second item... diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index c9f1cdd7e37..698fa17956a 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -13,7 +13,7 @@ ensure that all the documentation looks the same across the project. To improve the documentation you need to: - Start by `cloning the repository `_; -- Follow the `guidelines `_ to the corresponding documentation part you want to develop; +- Follow the `guidelines `_ to the corresponding documentation part you want to develop; - Check the new documentation by `viewing the documentaion `_ Clone the repository @@ -32,8 +32,8 @@ development mode by running this code: Guidelines ---------- -Our documentation tries to follow a structure principle that respects four different functions of the documentation -that fulfils the possible needs of people working with our tool at different times, in different circumstances. +Our documentation tries to follow a structure principle that respects four different functions of the documentation. +Each of them fulfills a different need for people working with our tool at different times, in different circumstances. Here is an overview of how our documentation is organized to help you know where you should include your contributions. Each section has their own guidelines that must be followed when creating new content. From 0e89ba94a485eb4680a99f8db14dbdf0ddd8a3c2 Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Wed, 15 Jan 2025 12:03:03 +0100 Subject: [PATCH 37/42] Apply suggestions from code review Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- .../getting_started/write_doc/guidelines_tutorials.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/getting_started/write_doc/guidelines_tutorials.rst b/doc/source/getting_started/write_doc/guidelines_tutorials.rst index 00529bbc3f8..951fd67519d 100644 --- a/doc/source/getting_started/write_doc/guidelines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guidelines_tutorials.rst @@ -148,8 +148,8 @@ The tutorial is divided in two main parts: Header ^^^^^^ -This first part is essential for clarity, organization and usability of the tutorial. It establishes the tutorials -purpose, making it easy to understand what is going to be explained and reference it within the other parts of +This first part is essential for clarity, organization and usability of the tutorial. It establishes the purpose +of the tutorial, making it easier to understand what is going to be explained and reference it within the other parts of the documentation. The header must have : @@ -274,8 +274,8 @@ These tabs looks like: # Code block 4 -You can also use tabs if you want to show different approaches to one step and it would be more clear -to have the code blocks in different tabs. You can see an example of this case in the +You can also use tabs if you want to show different approaches to one step and it having the code blocks +in different tabs is clearer. You can see an example of this in the :ref:`ref_tutorials_animate_time` tutorial. From e8273833a6b6deb03d69bb7acdc2f53d833e2793 Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Thu, 16 Jan 2025 12:18:04 +0100 Subject: [PATCH 38/42] Apply suggestions from code review Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- .../getting_started/write_doc/guidelines_tutorials.rst | 4 ++-- .../write_doc/tutorial_content_template.rst | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/getting_started/write_doc/guidelines_tutorials.rst b/doc/source/getting_started/write_doc/guidelines_tutorials.rst index 951fd67519d..52fba6bf225 100644 --- a/doc/source/getting_started/write_doc/guidelines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guidelines_tutorials.rst @@ -355,14 +355,14 @@ guide to ensure that all code looks the same across the project. :octicon:`check-circle-fill` **Correct** - First explanation + Explanation for a first code block and its output .. code-block:: # Code comment 1 code1 - Second explanation + Explanation for a second code block and its output .. code-block:: diff --git a/doc/source/getting_started/write_doc/tutorial_content_template.rst b/doc/source/getting_started/write_doc/tutorial_content_template.rst index e0f0bea6cd2..a9ab884794f 100644 --- a/doc/source/getting_started/write_doc/tutorial_content_template.rst +++ b/doc/source/getting_started/write_doc/tutorial_content_template.rst @@ -2,7 +2,7 @@ Tabs for different solvers -------------------------- -Here you have to make an implementation but it is different for the different solvers +Showcase a different script for each supported solvers .. tab-set:: @@ -41,13 +41,13 @@ Here you have to make an implementation but it is different for the different so Bullet lists ------------ -Here you enumerate something: +Enumerate something: - something 1; - something 2; - something 3. -Here you enumerate something with a numbered list: +Enumerate something with a numbered list: #. something 1; #. something 2; @@ -56,7 +56,7 @@ Here you enumerate something with a numbered list: Bullet lists with explanations between items -------------------------------------------- -Here you enumerate something and reference them to use each item as a subheading: +Enumerate something and reference them to use each item as a subheading: - :ref:`Something 1`; - :ref:`Something 2`; From 703786b4855b969e96c194c2dbe391197ea2c83a Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Thu, 16 Jan 2025 12:20:09 +0100 Subject: [PATCH 39/42] Update doc/source/getting_started/write_doc/guidelines_tutorials.rst Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- doc/source/getting_started/write_doc/guidelines_tutorials.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/getting_started/write_doc/guidelines_tutorials.rst b/doc/source/getting_started/write_doc/guidelines_tutorials.rst index 52fba6bf225..5dab2942849 100644 --- a/doc/source/getting_started/write_doc/guidelines_tutorials.rst +++ b/doc/source/getting_started/write_doc/guidelines_tutorials.rst @@ -372,6 +372,8 @@ guide to ensure that all code looks the same across the project. .. grid-item-card:: :octicon:`x-circle-fill` **Incorrect** + + A single broad explanation for two steps with outputs mixed together .. code-block:: From 23e52955498a73bda2e76210dfd8e239d3d4a28e Mon Sep 17 00:00:00 2001 From: Luisa Felix Salles Date: Fri, 17 Jan 2025 13:50:56 +0100 Subject: [PATCH 40/42] Apply suggestions from code review Co-authored-by: Paul Profizi <100710998+PProfizi@users.noreply.github.com> --- doc/source/getting_started/write_doc/index.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index 698fa17956a..8cbfd0a56f6 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -55,7 +55,7 @@ Each section has their own guidelines that must be followed when creating new co **Function:** Teach how to get started and use PYDPF-core step by step They are designed to teach how to perform a task and understand the underlying concepts, - providing detailed explanations at each stage. + providing detailed explanations at each stage. The task is built around the application of specific features. +++ .. rubric:: Guidelines @@ -74,7 +74,7 @@ Each section has their own guidelines that must be followed when creating new co **Function:** Show how to solve specifics key problems They showcase specific key problems and use-cases. They are more advanced than - tutorials and assume some knowledge on PyDPF-Core. + tutorials as they present end-to-end engineering workflows and assume basic knowledge of PyDPF-Core. +++ .. rubric:: Guidelines @@ -90,10 +90,9 @@ Each section has their own guidelines that must be followed when creating new co Understanding oriented ^^^^^^^^^^^^^^^^^^^^^^ - **Function:** Provide useful background explanation on PyDPF-Core + **Function:** Provide useful theoretical explanations for PyDPF-Core - They discuss and explain key topics and concepts providing enabling the reader to understand our - tool. + They discuss and explain key DPF principles and concepts, enabling the reader to understand the spirit of the underlying tool. +++ .. rubric:: Guidelines @@ -112,8 +111,7 @@ Each section has their own guidelines that must be followed when creating new co **Function:** Describe PyDPF-Core APIs - They contain technical reference on how PyDPF-Core works and how to use it but assume that you have - a basic understanding of key concepts. + They contain technical reference on how PyDPF-Core works and how to use it but assume basic understanding of key DPF concepts. It is generated automatically along the documentation and is based on the source code. +++ .. rubric:: Guidelines From ec1868390879938be80b953406095929f881f34f Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Fri, 17 Jan 2025 13:59:07 +0100 Subject: [PATCH 41/42] updates the index.rst of the write doc section --- doc/source/getting_started/write_doc/index.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/getting_started/write_doc/index.rst b/doc/source/getting_started/write_doc/index.rst index 8cbfd0a56f6..500a5062127 100644 --- a/doc/source/getting_started/write_doc/index.rst +++ b/doc/source/getting_started/write_doc/index.rst @@ -111,7 +111,9 @@ Each section has their own guidelines that must be followed when creating new co **Function:** Describe PyDPF-Core APIs - They contain technical reference on how PyDPF-Core works and how to use it but assume basic understanding of key DPF concepts. It is generated automatically along the documentation and is based on the source code. + They contain technical reference on how PyDPF-Core works and how to use it but assume basic + understanding of key DPF concepts. It is generated automatically along the documentation and + is based on the source code. +++ .. rubric:: Guidelines @@ -122,12 +124,10 @@ View the documentation ---------------------- Documentation for the latest stable release of PyDPF-Core is hosted at -`PyDPF-Core Documentation `_. +`PyDPF-Core 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. +You can locally build the documentation by following the steps in +`Contributing `_ in the *PyAnsys Developer's Guide*. .. toctree:: :maxdepth: 2 From c30027d2bea80703d2c70e4e0fe4d2b20eb1773e Mon Sep 17 00:00:00 2001 From: luisaFelixSalles Date: Fri, 17 Jan 2025 13:59:31 +0100 Subject: [PATCH 42/42] add a new link to the links_and_refs.rst file --- doc/source/links_and_refs.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/links_and_refs.rst b/doc/source/links_and_refs.rst index 94d4218bcf4..f6590b5549e 100644 --- a/doc/source/links_and_refs.rst +++ b/doc/source/links_and_refs.rst @@ -6,6 +6,7 @@ .. _pydpfcore_issues: https://github.com/ansys/pydpf-core/issues .. _pydpfcore_discussions: https://github.com/ansys/pydpf-core/discussions .. _pydpfcore_latest_release: https://github.com/ansys/pydpf-core/releases/latest +.. _pydpfcore_documentation: https://dpf.docs.pyansys.com/ .. Pyansys .. _pyansys: https://docs.pyansys.com/version/dev/