docs: task_inputs and deprecated

doc/howtoguides.rst

@@ -0,0 +1,8 @@
+How-to Guides
+=============
+
+.. toctree::
+    :maxdepth: 1
+
+    howtoguides/task_inputs
+    howtoguides/deprecate

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.

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},
+        ),
+    ]

doc/index.rst

@@ -9,4 +9,5 @@ of the `European Synchrotron <https://www.esrf.fr/>`_.
 .. toctree::
     :hidden:
 
+    howtoguides
     reference

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):