Add tutorials and update User Guide layout

doc/source/api/index.rst

@@ -3,8 +3,10 @@
 =============
 API reference
 =============
+
 .. toctree::
    :maxdepth: 2
    :caption: API reference
 
    ansys.dpf.core
+

doc/source/conf.py

@@ -7,7 +7,7 @@
 import pyvista
 from ansys.dpf.core import __version__, server, server_factory
 from ansys.dpf.core.examples import get_example_required_minimum_dpf_version
-from ansys_sphinx_theme import pyansys_logo_black, ansys_favicon, get_version_match
+from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_light_mode, pyansys_logo_dark_mode
 
 # Manage errors
 pyvista.set_error_output_file("errors.txt")
@@ -74,6 +74,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.autosummary",
     "enum_tools.autoenum",
     "nbsphinx",
     "sphinx.ext.autosectionlabel",
@@ -193,7 +194,6 @@ def reset_servers(gallery_conf, fname, when):
 # -- Options for HTML output -------------------------------------------------
 html_short_title = html_title = "PyDPF-Core"
 html_theme = "ansys_sphinx_theme"
-html_logo = pyansys_logo_black
 html_favicon = ansys_favicon
 html_theme_options = {
     "github_url": "https://github.com/ansys/pydpf-core",
@@ -202,6 +202,10 @@ def reset_servers(gallery_conf, fname, when):
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],
+    "logo" : {
+        "image_dark": pyansys_logo_dark_mode,
+        "image_light": pyansys_logo_light_mode,
+    },
     "switcher": {
         "json_url": f"https://{cname}/versions.json",
         "version_match": get_version_match(__version__),

doc/source/index.rst

@@ -193,5 +193,5 @@ To reach the project support team, email `pyansys.core@ansys.com <pyansys.core@a
    examples/index
    api/index
    operator_reference
-   concepts/index
    contributing
+

doc/source/substitution_solvers.rst

@@ -0,0 +1,54 @@
+.. _ref_substitution_solvers:
+
+.. Information about the interactions between apps and DPF
+
+.. Files formats
+
+.. MAPDL
+.. |MAPDL_files| replace:: .rst, .mode, .rfrq, .rdsp
+
+.. LSDYNA
+.. |LS-DYNA_files| replace:: .d3plot, .binout
+
+.. Fluent
+.. |Fluent_files1| replace:: **CFF restart files** : .cas.h5, dat.h5
+.. |Fluent_files2| replace:: **Project files** : .flprj
+
+.. CFX
+.. |CFX_files1| replace:: **CFF files** : .cas.cff.res, dat.cff.res
+.. |CFX_files2| replace:: **Project files** : .flprj
+
+
+.. Server version
+
+.. MAPDL
+.. |MAPDL_version| replace:: **1.0** and later (*Ansys 2021 R1*)
+
+.. LSDYNA
+.. |LS-DYNA_version| replace:: **4.0** and later (*Ansys 2022 R2*)
+
+.. Fluent
+.. |Fluent_version| replace:: **7.0** and later (*Ansys 2024 R1 pre0*)
+
+.. CFX
+.. |CFX_version| replace:: **7.0** and later (*Ansys 2024 R1 pre0*)
+
+.. DPF examples
+
+.. MAPDL
+.. |MAPDL_example| replace::  :ref:`ref_basic_example`
+
+.. LSDYNA
+.. |LS-DYNA_example| replace:: :ref:`examples_lsdyna`
+
+.. Fluent
+.. |Fluent_example1| replace:: :ref:`ref_fluids_model`
+.. |Fluent_example2| replace:: :ref:`ref_fluids_mesh`
+.. |Fluent_example3| replace:: :ref:`ref_fluids_results`
+
+.. CFX
+.. |CFX_example1| replace:: :ref:`examples_cfx`
+.. |CFX_example2| replace:: :ref:`ref_fluids_model`
+.. |CFX_example3| replace:: :ref:`ref_fluids_mesh`
+.. |CFX_example4| replace:: :ref:`ref_fluids_results`
+

doc/source/user_guide/how_to.rst

@@ -3,17 +3,6 @@
 How-tos
 ~~~~~~~
 
-.. toctree::
-    :hidden:
-
-    plotting.rst
-    custom_operators.rst
-    dpf_server.rst
-    server_types.rst
-    server_context.rst
-    xmlfiles.rst
-
-
 .. card-carousel:: 2
 
     .. card:: Plot

doc/source/user_guide/index.rst

@@ -13,6 +13,35 @@ The goals of this section are to:
  - Describe the most-used DPF entities and how they can help you to access and modify solver data.
  - Provide simple how-tos for tackling the most common use cases.
 
+Concepts
+--------
+
+.. card-carousel:: 2
+
+    .. card:: Concepts and terminology
+       :link: user_guide_concepts
+       :link-type: ref
+       :width: 25%
+       :text-align: center
+
+       .. image:: ../images/drawings/book-logo.png
+
+    .. card:: Ways of using DPF
+       :link: user_guide_waysofusing
+       :link-type: ref
+       :width: 25%
+       :text-align: center
+
+       .. image:: ../images/drawings/using-dpf.png
+
+    .. card:: Using DPF: Step by step
+       :link: user_guide_stepbystep
+       :link-type: ref
+       :width: 25%
+       :text-align: center
+
+       .. image:: ../images/drawings/checklist.png
+
 
 .. include::
    main_entities.rst
@@ -22,7 +51,34 @@ The goals of this section are to:
 
 
 Troubleshooting
-~~~~~~~~~~~~~~~
+---------------
 
 .. toctree::
-   troubleshooting
+    :maxdepth: 2
+    :hidden:
+    :caption: Concepts
+
+    concepts.rst
+    waysofusing.rst
+    stepbystep.rst
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: Tutorials
+
+    model
+    operators
+    fields_container
+    plotting
+    custom_operators
+    server_context
+    server_types
+    xmlfiles
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: Troubleshooting
+
+    troubleshooting

doc/source/user_guide/main_entities.rst

@@ -1,14 +1,13 @@
 .. _ref_main_entities:
 
-DPF most-used entities
-~~~~~~~~~~~~~~~~~~~~~~
+Tutorials
+---------
 
-.. toctree::
-   :hidden:
+The following tutorials show how to use basic features of PyDPF-Core
+at different steps in a typical data analysis process.
 
-   model
-   operators
-   fields_container
+Define the origins of the data
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. card-carousel:: 2
 
@@ -18,24 +17,24 @@ DPF most-used entities
        :width: 25%
        :text-align: center
 
-       .. image:: ../images/drawings/model.png
+    .. card:: DPF model
+       :link: user_guide_model
+       :link-type: ref
+       :width: 25%
+       :text-align: center
 
     .. card:: Fields container and fields
        :link: ref_user_guide_fields_container
        :link-type: ref
        :width: 25%
        :text-align: center
 
-       .. image:: ../images/drawings/field.png
-
     .. card:: Operators
        :link: ref_user_guide_operators
        :link-type: ref
        :width: 25%
        :text-align: center
 
-       .. image:: ../images/drawings/small_operator.svg
-
 
 
 

examples/README.txt

@@ -4,3 +4,5 @@
 Examples
 ========
 These examples demonstrate the behavior and usage of DPF-Core.
+
+

requirements/requirements_docs.txt

@@ -1,17 +1,18 @@
-ansys_sphinx_theme==0.16.5
+ansys-sphinx-theme[autoapi]==1.0.8
 enum-tools[sphinx]==0.12.0
 graphviz==0.20.1
 imageio==2.35.1
 imageio-ffmpeg==0.4.7
 nbsphinx==0.9.3
+numpydoc==1.8.0
 pypandoc==1.13
 pytest-sphinx==0.6.3
 pyvista==0.44.1
 sphinx==7.1.0
 sphinx-autobuild==2024.2.4
 sphinx-copybutton==0.5.2
-sphinx-gallery==0.17.0
+sphinx-gallery==0.17.1
 sphinx-notfound-page==1.0.0
 sphinx-reredirects==0.1.3
-sphinx_design==0.6.0
+sphinx_design==0.6.1
 sphinxcontrib-napoleon==0.7