Doc: migrate engine pages from ewoks.esrf.fr

doc/_static/custom.css

@@ -1,7 +1,19 @@
 button.copybtn {
-    opacity: 0.3;
+  opacity: 0.3;
 }
 
 button.copybtn:hover {
-    opacity: 1;
+  opacity: 1;
+}
+
+.table td.red {
+  color: red;
+}
+
+.table td.green {
+  color: green;
+}
+
+.table td.orange {
+  color: orange;
 }

doc/howtoguides.rst

@@ -6,17 +6,44 @@ across different environments and interfaces. This guide presents several possib
 ways of handling workflows with *Ewoks*, whether through command-line tools,
 Python APIs, graphical interfaces, or REST services.
 
+Getting started
+---------------
+
 .. toctree::
     :maxdepth: 1
 
-    howtoguides/running_workflows
-    howtoguides/python
     howtoguides/inspect_workflows
-    howtoguides/job
     howtoguides/gui
+    howtoguides/python
+    howtoguides/engines
+
+Automation
+----------
+
+.. toctree::
+    :maxdepth: 1
+
     howtoguides/rest
+    howtoguides/job
+
+Advanced execution
+------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    howtoguides/running_workflows
     howtoguides/benchmark
     howtoguides/ewoks_events
-    howtoguides/task_python
-    howtoguides/task_inputs
     howtoguides/ewoks_ppf
+
+
+For developers
+--------------
+
+.. toctree::
+    :maxdepth: 1
+
+    howtoguides/task_inputs
+    howtoguides/task_python
+    howtoguides/new_engine

doc/howtoguides/engines.rst

@@ -0,0 +1,114 @@
+Choosing an engine for execution
+=================================
+
+Ewoks workflows can be executed using several engines, each with its own capabilities:
+
+- `Dask <https://www.dask.org/>`_: Distributed and parallel computing framework.
+- `Pypushflow <https://pypushflow.readthedocs.io/>`_: Scheduler for acyclic and cyclic task graphs.
+- `Orange <https://orangedatamining.com/>`_: Visual programming and data visualization platform.
+
+New engines can be added following the :doc:`./new_engine` procedure.
+
+Using a Supported Engine
+------------------------
+
+To run workflows with a specific engine, install the appropriate extra:
+
+.. code-block:: bash
+
+   pip install ewoks[dask]     # For Dask
+   pip install ewoks[ppf]      # For Pypushflow
+   pip install ewoks[orange]   # For Orange
+
+If no engine is installed, Ewoks defaults to a basic sequential engine (``"core"``).
+
+To specify the engine explicitly, use the ``--engine`` option:
+
+.. code-block:: bash
+
+   ewoks execute --test demo --engine dask
+
+.. warning::
+
+   **Orange execution is GUI-driven** and cannot run without the Orange GUI.
+
+   Running:
+
+   .. code-block:: bash
+
+      ewoks execute --test demo --engine orange
+
+   ...will open the Orange GUI, where you can edit the workflow.
+
+   To execute it:
+
+   - Double-click on ``task0`` in the workflow.
+   - Use the **Trigger** button in the **Task** widget.
+
+   For guidance, see `Orange's getting started docs <https://orangedatamining.com/getting-started/>`_.
+
+
+Engine Feature Comparison
+-------------------------
+
+Some engines support more advanced features, like loops or GUI interaction:
+
+.. raw:: html
+
+   <table class="table">
+   <thead>
+   <tr>
+     <th>engine</th>
+     <th>Loops</th>
+     <th>Conditional Links</th>
+     <th>Parallel execution</th>
+     <th>Interaction (GUI)</th>
+     <th>Native support</th>
+   </tr>
+   </thead>
+   <tbody>
+   <tr>
+     <td><code>core</code></td>
+     <td class="red">✗</td>
+     <td class="red">✗</td>
+     <td class="red">✗</td>
+     <td class="red">✗</td>
+     <td class="green">✓</td>
+   </tr>
+   <tr>
+     <td><code>dask</code></td>
+     <td class="red">✗</td>
+     <td class="red">✗</td>
+     <td class="green">✓</td>
+     <td class="red">✗</td>
+     <td class="green">✓</td>
+   </tr>
+   <tr>
+     <td><code>ppf</code></td>
+     <td class="green">✓</td>
+     <td class="green">✓</td>
+     <td class="green">✓</td>
+     <td class="red">✗</td>
+     <td class="green">✓</td>
+   </tr>
+   <tr>
+     <td><code>"orange"</code></td>
+     <td class="red">✗</td>
+     <td class="red">✗</td>
+     <td class="orange">✓</td>
+     <td class="green">✓</td>
+     <td class="red">✗</td>
+   </tr>
+   </tbody>
+   </table>
+
+
+
+.. note::
+
+   **Native support** means that Ewoks tasks can be executed without modification.
+
+   For Orange, you must wrap each Ewoks task in a corresponding Orange widget. See the
+   `Orange widget tutorial <https://ewoksorange.readthedocs.io/en/stable/tutorials/my_first_widget.html>`_
+   in the ``ewoksorange`` documentation.
+

doc/howtoguides/new_engine.rst

@@ -0,0 +1,63 @@
+Adding a new engine to Ewoks
+============================
+
+This page shows how to create a custom engine named ``"abc"`` which can be used like this
+
+.. code-block:: bash
+
+   ewoks execute --test demo --engine abc
+
+Create a Python package with the appropriate entry point in ``pyproject.toml``:
+
+.. code-block:: toml
+
+   [project]
+   name = "ewoksabc"
+
+   [project.entry-points."ewoks.engines"]
+   "abc" = "ewoksabc.engine:AbcWorkflowEngine"
+
+Your engine must implement the abstract interface ``WorkflowEngine`` from ``ewokscore``:
+
+.. code-block:: python
+
+   from ewokscore.graph import TaskGraph
+   from ewokscore.engine_interface import WorkflowEngine
+
+   class AbcWorkflowEngine(WorkflowEngine):
+
+       def execute_graph(self, graph: TaskGraph, ...) -> Optional[dict]:
+           ...
+
+
+(Optional) Workflow Serialization Support
+------------------------------------------
+
+If your engine also handles workflow (de)serialization (e.g., from ``.xyz`` files), add another entry point:
+
+.. code-block:: toml
+
+   [project.entry-points."ewoks.engines.serialization.representations"]
+   "xyz" = "ewoksabc.engine:AbcWorkflowEngine"
+
+Your engine should implement ``WorkflowEngineWithSerialization``:
+
+.. code-block:: python
+
+   from ewokscore.engine_interface import WorkflowEngineWithSerialization
+
+   class AbcWorkflowEngine(WorkflowEngineWithSerialization):
+
+       def execute_graph(self, graph: TaskGraph, ...) -> Optional[dict]:
+           ...
+
+       def deserialize_graph(self, graph: Any, ...) -> TaskGraph:
+           ...
+
+       def serialize_graph(self, graph: TaskGraph, ...) -> Any:
+           ...
+
+       def get_graph_representation(self, graph: Any) -> Optional[str]:
+           ...
+
+This allows Ewoks to recognize and delegate serialization/deserialization to your engine when the `ewoksabc` package is installed.