updates

Author: luisaFelixSalles

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_guide_lines_add_new_tutorial_section>`;
-- :ref:`New tutorials<ref_guide_lines_add_new_tutorial>`.
+- :ref:`New tutorials section<ref_guide_lines_add_new_tutorial_section>`;
+- :ref:`New tutorial<ref_guide_lines_add_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<file_name>` :jupyter-download-notebook:`Download tutorial as notebook<file_name>`
 
+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<jupyter_sphinx_ext>`_ 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
 ~~~~~~~~~~~~~~

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<file_name>` :jupyter-download-notebook:`Download tutorial as notebook<file_name>`
+
+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
+----------
+