Changes in the user guide layout (#1763)

* add concepts intro in the user guide index page * add tutorials concept (from the main entities documents) * organise and adapt the how-to section * organise and adapt the troubleshooting section * organise and adapt the troubleshooting section and final sidebar * changes in the troubleshooting index page * changes in the how to index page * changes in the concepts index page * changes in the layout of the index pages * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * corrections after first revision * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * Add sphinx-exec-code to doc requirements * corrections files path * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> * Apply suggestions from code review Co-authored-by: Paul Profizi <[email protected]> --------- Co-authored-by: Paul Profizi <[email protected]>
ansys · Sep 24, 2024 · 2d4f565 · 2d4f565
1 parent 0a6f461
commit 2d4f565
Show file tree

Hide file tree

Showing 30 changed files with 270 additions and 175 deletions.
diff --git a/doc/source/user_guide/concepts/concepts.rst b/doc/source/user_guide/concepts/concepts.rst
@@ -67,7 +67,7 @@ Concept summary
 ---------------
 This image summarizes the preceding concepts:
 
-.. image:: ../images/drawings/field-breakdown.png
+.. image:: ../../images/drawings/field-breakdown.png
 
 
 Operators
@@ -79,7 +79,7 @@ You use :ref:`ref_dpf_operators_reference` to create, transform, and stream the
 - The input and output pins, like those in an integrated circuit in electronics,
   submit data to the operator and output the computed result from the operator.
 
-.. image:: ../images/drawings/OperatorPins.png
+.. image:: ../../images/drawings/OperatorPins.png
 
 Workflows
 ---------
@@ -90,10 +90,10 @@ to operators, which computes requested outputs.
 Think of a workflow as a black box in which some operators are chained, 
 computing the information for which the workflow is made:
 
-.. image:: ../images/drawings/Workflow1.png
+.. image:: ../../images/drawings/Workflow1.png
 
 The following image shows operators that have been chained together to create a
 total deformation workflow. You can use this workflow in any simulation
 workflow with any data sources as inputs.
 
-.. image:: ../images/drawings/Workflow2.png
+.. image:: ../../images/drawings/Workflow2.png
diff --git a/doc/source/user_guide/concepts/index.rst b/doc/source/user_guide/concepts/index.rst
@@ -1,44 +1,28 @@
-.. _ref_concepts:
+.. _ref_concepts_index:
 
-========
 Concepts
-========
+--------
 
-This section provides in-depth descriptions and explanations of DPF concepts, including terminology.
+.. grid:: 3
+    :gutter: 2
 
-DPF concepts
-~~~~~~~~~~~~
-
-.. toctree::
-   :hidden:
-
-   concepts.rst
-   waysofusing.rst
-   stepbystep.rst
-
-
-.. card-carousel:: 2
-
-    .. card:: Concepts and terminology
+    .. grid-item-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
+    .. grid-item-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
+    .. grid-item-card:: Using DPF: Step by step
        :link: user_guide_stepbystep
        :link-type: ref
-       :width: 25%
        :text-align: center
 
-       .. image:: ../images/drawings/checklist.png
+       .. image:: ../images/drawings/checklist.png
diff --git a/doc/source/user_guide/concepts/stepbystep.rst b/doc/source/user_guide/concepts/stepbystep.rst
@@ -53,11 +53,11 @@ Define fields
 A **field** is a container of simulation data. In numerical simulations,
 result data is defined by values associated with entities:
 
-.. image:: ../images/drawings/values-entities.png
+.. image:: ../../images/drawings/values-entities.png
 
 Therefore, a field of data might look something like this:
 
-.. image:: ../images/drawings/field.png
+.. image:: ../../images/drawings/field.png
 
 This code shows how to define a field from scratch:
 
@@ -83,7 +83,7 @@ be a set of mesh IDs, geometric entity IDs, time domain, or frequency domain.
 
 You specify the set of entities by defining a range of IDs:
 
-.. image:: ../images/drawings/scoping-eg.png
+.. image:: ../../images/drawings/scoping-eg.png
 
 You must define a scoping prior to its use in the transformation data workflow.
 
@@ -109,13 +109,13 @@ A **field container** holds a set of fields. It is used mainly for
 transient, harmonic, modal, or multi-step analyses. This image
 explains its structure:
 
-.. image:: ../images/drawings/field-con-overview.png
+.. image:: ../../images/drawings/field-con-overview.png
 
 A field container is a vector of fields. Fields are ordered with labels
 and IDs. Most commonly, a field container is scoped on the time label,
 and the IDs are the time or frequency sets:
 
-.. image:: ../images/drawings/field-con.png
+.. image:: ../../images/drawings/field-con.png
 
 You can define a field container in multiple ways:
 
@@ -162,14 +162,14 @@ An operator takes input from a field, field container, or scoping using
 an input pin. Based on what it is designed to do, the operator computes
 an output that it passes to a field or field container using an output pin.
 
-.. image:: ../images/drawings/circuit.png
+.. image:: ../../images/drawings/circuit.png
 
 Comprehensive information on operators is available in :ref:`ref_dpf_operators_reference`.
 In the **Available Operators** area for either the **Entry** or **Premium** operators,
 you can either type a keyword in the **Search** option
 or browse by operator categories:
 
-.. image:: ../images/drawings/help-operators.png
+.. image:: ../../images/drawings/help-operators.png
 
 The page for each operator describes how the operator transforms data,
 indicates input and output data, and provides usage examples.
@@ -185,7 +185,7 @@ Defining an operator consists of three steps:
 This image shows how the page for an operator provides a usage example for each available
 language (IronPython, CPython, and C++).
 
-.. image:: ../images/drawings/operator-def.png
+.. image:: ../../images/drawings/operator-def.png
 
 This code shows how to define an operator from a model:
 
@@ -210,7 +210,7 @@ the input to another operator.
 This image shows how you would get the norm of a resulting vector from the
 dot product of two vectors:
 
-.. image:: ../images/drawings/connect-operators.png
+.. image:: ../../images/drawings/connect-operators.png
 
 This code shows how to define a generic workflow that computes the minimum
 of displacement by chaining the ``U`` and ``min_max_fc`` operators:

diff --git a/doc/source/user_guide/concepts/waysofusing.rst b/doc/source/user_guide/concepts/waysofusing.rst
@@ -29,7 +29,7 @@ enabled using the DPF Server application.
 These capabilities can be accessed through client APIs, as shown here:
 
 
-.. image:: ../images/drawings/apis_2.png
+.. image:: ../../images/drawings/apis_2.png
 
 
 1. DPF server application can be accessed using Ansys Inc product, or DPF Server package (see :ref:`ref_dpf_server`) available on the Customer portal.
@@ -71,12 +71,12 @@ files. You can use it to generate TH-plots, screenshots, and animations or
 to create custom result plots using the `numpy <https://numpy.org/>`_
 and `matplotlib <https://matplotlib.org/>`_ packages.
 
-.. image:: ../images/drawings/dpf-reports.png
+.. image:: ../../images/drawings/dpf-reports.png
 
 Mechanical
 ~~~~~~~~~~
 **DPF in Mechanical** uses IronPython and is accessible with the **ACT Console**.
 Use it to perform custom postprocessing and visualization of results directly 
 within the Mechanical application.
 
-.. image:: ../images/drawings/dpf-mech.png
+.. image:: ../../images/drawings/dpf-mech.png
diff --git a/...ide/create_sites_for_python_operators.ps1 → ...-to/create_sites_for_python_operators.ps1 b/...ide/create_sites_for_python_operators.ps1 → ...-to/create_sites_for_python_operators.ps1
diff --git a/...uide/create_sites_for_python_operators.sh → ...w-to/create_sites_for_python_operators.sh b/...uide/create_sites_for_python_operators.sh → ...w-to/create_sites_for_python_operators.sh
diff --git a/...rce/user_guide/custom_operator_example.py → ...r_guide/how-to/custom_operator_example.py b/...rce/user_guide/custom_operator_example.py → ...r_guide/how-to/custom_operator_example.py
diff --git a/doc/source/user_guide/custom_operators.rst → ...ce/user_guide/how-to/custom_operators.rst b/doc/source/user_guide/custom_operators.rst → ...ce/user_guide/how-to/custom_operators.rst
@@ -34,8 +34,8 @@ installer's Python interpreter.
 
 #. Download the script for you operating system:
 
-   - For Windows, download this :download:`PowerShell script </user_guide/install_ansys_dpf_core_in_ansys.ps1>`.
-   - For Linux, download this :download:`Shell script </user_guide/install_ansys_dpf_core_in_ansys.sh>`
+   - For Windows, download this :download:`PowerShell script </user_guide/how-to/install_ansys_dpf_core_in_ansys.ps1>`.
+   - For Linux, download this :download:`Shell script </user_guide/how-to/install_ansys_dpf_core_in_ansys.sh>`
 
 #. Run the downloaded script for installing with optional arguments:
 
@@ -48,8 +48,8 @@ If you ever want to uninstall the ``ansys-dpf-core`` module from the Ansys insta
 
 #. Download the script for your operating system:
 
-   - For Windows, download this :download:`PowerShell script </user_guide/uninstall_ansys_dpf_core_in_ansys.ps1>`.
-   - For Linux, download this :download:`Shell script </user_guide/uninstall_ansys_dpf_core_in_ansys.sh>`.
+   - For Windows, download this :download:`PowerShell script </user_guide/how-to/uninstall_ansys_dpf_core_in_ansys.ps1>`.
+   - For Linux, download this :download:`Shell script </user_guide/how-to/uninstall_ansys_dpf_core_in_ansys.sh>`.
 
 3. Run the downloaded script for uninstalling with the optional argument:
 

diff --git a/...urce/user_guide/custom_operators_deps.rst → ...er_guide/how-to/custom_operators_deps.rst b/...urce/user_guide/custom_operators_deps.rst → ...er_guide/how-to/custom_operators_deps.rst
@@ -23,8 +23,8 @@ For this approach, do the following:
 
 #. Download the script for your operating system:
 
-   - For Windows, download this :download:`PowerShell script </user_guide/create_sites_for_python_operators.ps1>`.
-   - For Linux, download this :download:`Shell script </user_guide/create_sites_for_python_operators.sh>`.
+   - For Windows, download this :download:`PowerShell script </user_guide/how-to/create_sites_for_python_operators.ps1>`.
+   - For Linux, download this :download:`Shell script </user_guide/how-to/create_sites_for_python_operators.sh>`.
 
 3. Run the downloaded script with the mandatory arguments:
 

diff --git a/doc/source/user_guide/custom_plugin.xml → ...ource/user_guide/how-to/custom_plugin.xml b/doc/source/user_guide/custom_plugin.xml → ...ource/user_guide/how-to/custom_plugin.xml
diff --git a/doc/source/user_guide/how-to/index.rst b/doc/source/user_guide/how-to/index.rst
@@ -0,0 +1,39 @@
+.. _ref_how_to:
+
+Enriching DPF capabilities
+----------------------------------------
+
+.. grid:: 3
+    :gutter: 2
+
+    .. grid-item-card:: Create custom operators and plugins
+       :link: user_guide_custom_operators
+       :link-type: ref
+       :text-align: center
+
+       .. image:: ../images/drawings/plugin-logo.png
+          :width: 50%
+
+
+    .. grid-item-card:: Switch between local and remote server
+       :link: user_guide_server_types
+       :link-type: ref
+       :text-align: center
+
+       .. image:: ../images/drawings/remote_machines.png
+
+
+    .. grid-item-card:: Access Entry and Premium capabilities
+       :link: user_guide_server_context
+       :link-type: ref
+       :text-align: center
+
+       .. image:: ../images/drawings/entry_premium.png
+
+
+    .. grid-item-card:: Configure DPF plugins load
+       :link: user_guide_xmlfiles
+       :link-type: ref
+       :text-align: center
+
+       .. image:: ../images/drawings/xml.png
diff --git a/...guide/install_ansys_dpf_core_in_ansys.ps1 → ...ow-to/install_ansys_dpf_core_in_ansys.ps1 b/...guide/install_ansys_dpf_core_in_ansys.ps1 → ...ow-to/install_ansys_dpf_core_in_ansys.ps1
diff --git a/..._guide/install_ansys_dpf_core_in_ansys.sh → ...how-to/install_ansys_dpf_core_in_ansys.sh b/..._guide/install_ansys_dpf_core_in_ansys.sh → ...how-to/install_ansys_dpf_core_in_ansys.sh
diff --git a/doc/source/user_guide/server_context.rst → ...urce/user_guide/how-to/server_context.rst b/doc/source/user_guide/server_context.rst → ...urce/user_guide/how-to/server_context.rst
diff --git a/doc/source/user_guide/server_types.rst → ...source/user_guide/how-to/server_types.rst b/doc/source/user_guide/server_types.rst → ...source/user_guide/how-to/server_types.rst
diff --git a/...ide/uninstall_ansys_dpf_core_in_ansys.ps1 → ...-to/uninstall_ansys_dpf_core_in_ansys.ps1 b/...ide/uninstall_ansys_dpf_core_in_ansys.ps1 → ...-to/uninstall_ansys_dpf_core_in_ansys.ps1
diff --git a/...uide/uninstall_ansys_dpf_core_in_ansys.sh → ...w-to/uninstall_ansys_dpf_core_in_ansys.sh b/...uide/uninstall_ansys_dpf_core_in_ansys.sh → ...w-to/uninstall_ansys_dpf_core_in_ansys.sh
diff --git a/doc/source/user_guide/xmlfiles.rst → doc/source/user_guide/how-to/xmlfiles.rst b/doc/source/user_guide/xmlfiles.rst → doc/source/user_guide/how-to/xmlfiles.rst
diff --git a/doc/source/user_guide/how_to.rst b/doc/source/user_guide/how_to.rst
diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst
@@ -11,18 +11,55 @@ computation, customization, and remote postprocessing accessible in Python.
 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.
+ - Provide simple tutorials for tackling the most common use cases.
+ - Explain how to customize DPF behavior.
+ - Present some systematic approaches to determine the cause of a malfunction or failure when using DPF.
 
+.. include::
+   concepts/index.rst
+
+.. include::
+   tutorials/index.rst
 
 .. include::
-   main_entities.rst
+   how-to/index.rst
 
 .. include::
-   how_to.rst
+   troubleshooting/index.rst
+
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: Concepts
 
+    concepts/concepts.rst
+    concepts/waysofusing.rst
+    concepts/stepbystep.rst
 
-Troubleshooting
-~~~~~~~~~~~~~~~
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: Tutorials
+
+    tutorials/model.rst
+    tutorials/operators.rst
+    tutorials/fields_container.rst
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: Accessing and enriching DPF capabilities
+
+    how-to/plotting.rst
+    how-to/custom_operators.rst
+    how-to/server_context.rst
+    how-to/server_types.rst
+    how-to/xmlfiles.rst
 
 .. toctree::
-   troubleshooting
+    :maxdepth: 1
+    :hidden:
+    :caption: Troubleshooting
+
+    troubleshooting/troubleshooting.rst