From 3aefa3e711ae7d673a717eb12781ec3d10f6ff3e Mon Sep 17 00:00:00 2001
From: woutdenolf <woutdenolf@users.sf.net>
Date: Tue, 8 Sep 2026 11:56:53 +0200
Subject: [PATCH 1/2] docs: task_inputs and deprecated

---
 doc/howtoguides.rst             |  8 ++++
 doc/howtoguides/deprecate.rst   | 19 ++++++++++
 doc/howtoguides/task_inputs.rst | 66 +++++++++++++++++++++++++++++++++
 doc/index.rst                   |  1 +
 4 files changed, 94 insertions(+)
 create mode 100644 doc/howtoguides.rst
 create mode 100644 doc/howtoguides/deprecate.rst
 create mode 100644 doc/howtoguides/task_inputs.rst

diff --git a/doc/howtoguides.rst b/doc/howtoguides.rst
new file mode 100644
index 0000000..103c306
--- /dev/null
+++ b/doc/howtoguides.rst
@@ -0,0 +1,8 @@
+How-to Guides
+=============
+
+.. toctree::
+    :maxdepth: 1
+
+    howtoguides/task_inputs
+    howtoguides/deprecate
diff --git a/doc/howtoguides/deprecate.rst b/doc/howtoguides/deprecate.rst
new file mode 100644
index 0000000..807f58d
--- /dev/null
+++ b/doc/howtoguides/deprecate.rst
@@ -0,0 +1,19 @@
+Deprecate functionality
+=======================
+
+Use :func:`ewoksutils.deprecation_utils.deprecated` to deprecate a
+function:
+
+.. code-block:: python
+
+    from ewoksutils.deprecation_utils import deprecated
+
+
+    @deprecated("use new_function instead")
+    def old_function():
+        ...
+
+Calling ``old_function`` emits a ``DeprecationWarning`` with the given
+message.
+
+Use the message to indicate the replacement whenever possible.
\ No newline at end of file
diff --git a/doc/howtoguides/task_inputs.rst b/doc/howtoguides/task_inputs.rst
new file mode 100644
index 0000000..a9b0286
--- /dev/null
+++ b/doc/howtoguides/task_inputs.rst
@@ -0,0 +1,66 @@
+Task inputs
+===========
+
+Use :func:`ewoksutils.task_utils.task_inputs` to create inputs for a task.
+
+By task identifier
+------------------
+
+Select a task by its task identifier and provide its inputs:
+
+.. code-block:: python
+
+    from ewoksutils.task_utils import task_inputs
+
+    inputs = task_inputs(
+        task_identifier="ewokscore.tests.test_tasks.SumTask",
+        inputs={"a": 10, "b": 20},
+    )
+
+.. tip::
+
+    ``task_identifier`` can be a full task identifier or a suffix of one.
+    For example, ``task_identifier="SumTask"`` matches
+    ``"ewokscore.tests.test_tasks.SumTask"``.
+
+By task ID
+----------
+
+For a workflow with explicit task IDs, select the task by its ID:
+
+.. code-block:: python
+
+    inputs = task_inputs(
+        id="sum_task",
+        inputs={"a": 10, "b": 20},
+    )
+
+By task label
+-------------
+
+A task can also be selected by its label:
+
+.. code-block:: python
+
+    inputs = task_inputs(
+        label="sum",
+        inputs={"a": 10, "b": 20},
+    )
+
+Multiple tasks
+--------------
+
+Inputs for multiple tasks can be combined using their task identifiers:
+
+.. code-block:: python
+
+    inputs = [
+        *task_inputs(
+            task_identifier="LoadData",
+            inputs={"filename": "data.h5"},
+        ),
+        *task_inputs(
+            task_identifier="ProcessData",
+            inputs={"threshold": 0.5},
+        ),
+    ]
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index cd0b6a4..c5186b5 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -9,4 +9,5 @@ of the `European Synchrotron <https://www.esrf.fr/>`_.
 .. toctree::
     :hidden:
 
+    howtoguides
     reference

From 7f9dc5b911a0c1814c7015c988f28ae3e08ab334 Mon Sep 17 00:00:00 2001
From: woutdenolf <woutdenolf@users.sf.net>
Date: Tue, 8 Sep 2026 11:59:23 +0200
Subject: [PATCH 2/2] docs: fix error

---
 src/ewoksutils/cli_utils/cli_click.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/ewoksutils/cli_utils/cli_click.py b/src/ewoksutils/cli_utils/cli_click.py
index d4008ae..642f547 100644
--- a/src/ewoksutils/cli_utils/cli_click.py
+++ b/src/ewoksutils/cli_utils/cli_click.py
@@ -12,6 +12,9 @@ def add_click_options(args_list: List[CLIArg]):
     Decorator factory that adds Click arguments/options from a list of CLIArg objects.
 
     Example:
+
+    .. code-block:: python
+
         @click.command("mycommand")
         @add_click_options([...])
         def mycommand(cli_args: Namespace):