Writing tutorials#

You can improve the PyDPF-Core documentation by adding a:

New tutorials section;
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:

.
├── doc
│   ├── source
│   │    ├── api
│   │    ├── examples
│   │    ├── getting_started
│   │    ├── images
│   │    ├── user_guide
│   │    ├── conf.py
│   │    ├── index.rst
│   ├── styles
│   ├── make.bat

Tutorials are located in the doc/source/user_guide directory.

Adding a new tutorial section#

Download the new tutorial section template

Note

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 reside in a new folder such as doc/source/user_guide/tutorials/new_section_name.

.
├── doc
│   ├── source
│   │    ├── user_guide
│   │    │   ├── tutorials
│   │    │        ├── new_section

Structure#

The section folder must contain an index.rst file with:

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.

.. _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 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:

.. toctree::
    :maxdepth: 2
    :hidden:
    :caption: Tutorials

    tutorials/section_x/index.rst
    tutorials/section_y/index.rst
    tutorials/section_z/index.rst
    tutorials/new_section/index.rst

Adding a new tutorial#

Download the tutorial card template Download the tutorial structure template 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

.
├── doc
│   ├── source
│   │    ├── user_guide
│   │    │   ├── tutorials
│   │    │        ├── 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:

a tutorial title,
a short description,
badges for the applicable solvers,
a link (in this case, the reference tag) to the tutorial file.

Structure#

The tutorial is divided in two main parts:

Header
Content

Header#

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 :

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.

.. _ref_tutorial_template:

==============
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.

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

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:

.. _ref_tutorial_template:


==============
Tutorial title
==============

Here some text. Here we use the |MeshedRegion| substitution text

For more information about the predefined references, see the links and references file.

Content#

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#

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. These steps are generally similar to

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 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 headline characters (here: -).

Import result file
------------------

First, you ...

Extract the mesh
----------------

Then, you extract ...

Plot the mesh
-------------

Finally, you plot ...

Tabs#

You must use tabs when a step requires a solver-specific implementation.

These tabs looks like:

MAPDL

Explanation 1 …

# Code block 1

LSDYNA

Explanation 2 …

# Code block 2

Fluent

Explanation 3 …

# Code block 3

CFX

Explanation 4 …

# Code block 4

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 Animate data over time tutorial.

Code blocks#

The tutorials must have code blocks where you show how you actually implement the code. 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. It executes embedded code in a Jupyter kernel and embeds outputs of that code in the document:

Correct

.. jupyter-execute::

    # This is a executable code block
    from ansys.dpf import core as dpf

Incorrect

.. code-block::

    # This is a simple code block
    from ansys.dpf import core as dpf

Use comments within a code block to clarify the purpose of a line:

Correct

# Define the model
model = dpf.Model()

# Get the stress results
stress_fc = model.results.stress.eval()

Incorrect

model = dpf.Model()
stress_fc = model.results.stress.eval()

Split your code in several parts to include longer explanations in text format or force showing an intermediate code output:

Correct

Explanation for a first code block and its output

# Code comment 1
code1

Explanation for a second code block and its output

# Code comment 2
code2

Incorrect

A single broad explanation for two steps with outputs mixed together

# First explanation
# Code comment 1
code1

# Second explanation
# Code comment 2
code2

When using a PyDPF-Core object or method you must name arguments:

Correct

# Get the stress results
stress_fc = model.results.stress(time_scoping=time_steps).eval()

Incorrect

# 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

Correct

# Define the DataSources object
ds = dpf.DataSources()

Incorrect

# Define the data sources object
ds = dpf.DataSources()

# Define the Data Sources object
ds = dpf.DataSources()

Use blank lines between code lines for better clarity.

Correct

# 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()

Incorrect

# 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 Tutorials.

Correct

# 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)

Incorrect

# 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 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

Correct

Here we use the |MeshedRegion| substitution text

Rendered text:

Here is some text. Here we use the MeshedRegion substitution text

Incorrect

Here we do not use the MeshedRegion substitution text

Rendered text:

Here is some text. Here we do not use the MeshedRegion substitution text

Use bullet lists when enumerating items:

Correct

This operator accepts as arguments:

- A Result
- An Operator
- A FieldsContainer

Incorrect

This operator accepts a Result, an Operator or a
FieldsContainer as arguments.

Use a numbered list for ordered items:

Correct

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.

Incorrect

To extract the mesh you need to follow those steps:

- Get the result file;
- Create a Model;
- Get the MeshedRegion.

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.

Correct

Section title
-------------

This section presents two items:

- :ref:`Item 1 <ref_tutorial_name_item_1>`
- :ref:`Content<ref_tutorial_name_item_2>`

.. _ref_tutorial_name_item_1:

Item 1
^^^^^^

Presentation of the first item...

.. _ref_tutorial_name_item_2:

Item 2
^^^^^^

Presentation of the second item...

Incorrect

Section title
-------------

This section presents two items:

- Item 1
- Item 2

Item 1
^^^^^^
Presentation of the first item...

Item 2
^^^^^^
Presentation of the second item...

Section title
-------------

This section presents two items:

- Item 1
Presentation of the first item...


- Item 2
Presentation of the second item...