diff --git a/doc/_static/custom.css b/doc/_static/custom.css
index bd5b027..e06ae42 100644
--- a/doc/_static/custom.css
+++ b/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;
}
diff --git a/doc/howtoguides.rst b/doc/howtoguides.rst
index f63f866..9202670 100644
--- a/doc/howtoguides.rst
+++ b/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
diff --git a/doc/howtoguides/engines.rst b/doc/howtoguides/engines.rst
new file mode 100644
index 0000000..07f4ce0
--- /dev/null
+++ b/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 `_: Distributed and parallel computing framework.
+- `Pypushflow `_: Scheduler for acyclic and cyclic task graphs.
+- `Orange `_: 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 `_.
+
+
+Engine Feature Comparison
+-------------------------
+
+Some engines support more advanced features, like loops or GUI interaction:
+
+.. raw:: html
+
+
+
+
+ | engine |
+ Loops |
+ Conditional Links |
+ Parallel execution |
+ Interaction (GUI) |
+ Native support |
+
+
+
+
+ core |
+ ✗ |
+ ✗ |
+ ✗ |
+ ✗ |
+ ✓ |
+
+
+ dask |
+ ✗ |
+ ✗ |
+ ✓ |
+ ✗ |
+ ✓ |
+
+
+ ppf |
+ ✓ |
+ ✓ |
+ ✓ |
+ ✗ |
+ ✓ |
+
+
+ "orange" |
+ ✗ |
+ ✗ |
+ ✓ |
+ ✓ |
+ ✗ |
+
+
+
+
+
+
+.. 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 `_
+ in the ``ewoksorange`` documentation.
+
diff --git a/doc/howtoguides/new_engine.rst b/doc/howtoguides/new_engine.rst
new file mode 100644
index 0000000..1592c08
--- /dev/null
+++ b/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.
\ No newline at end of file