Improve task and defer docs

docs/howto/basics/defer.md

@@ -4,7 +4,7 @@ There are several ways to do this.
 
 In the following examples, the task will be:
 
-```
+```python
 @app.task(queue="some_queue")
 def my_task(a: int, b:int):
     pass
@@ -14,39 +14,62 @@ Task name is `my_module.my_task`.
 
 ## The direct way
 
-```
+By using the sync method:
+
+```python
 my_task.defer(a=1, b=2)
 ```
 
-## With parameters
+Or the async method:
 
+```python
+await my_task.defer_async(a=1, b=2)
 ```
+
+## With parameters
+
+Using the sync defer method:
+
+```python
 my_task.configure(
     lock="the name of my lock",
     schedule_in={"hours": 1},
     queue="not_the_default_queue"
 ).defer(a=1, b=2)
+
+# or
+await my_task.configure(
+    lock="the name of my lock",
+    schedule_in={"hours": 1},
+    queue="not_the_default_queue"
+).defer_async(a=1, b=2)
 ```
 
 See details in {py:meth}`Task.configure`
 
 ## Create a job pattern, launch multiple jobs
 
-```
+```python
 pattern = my_task.configure(task_kwargs={"a": 1})
 
 pattern.defer(b=2)
 pattern.defer(b=3)
 pattern.defer(b=4)
+# or
+await pattern.defer_async(b=2)
+await pattern.defer_async(b=3)
+await pattern.defer_async(b=4)
 ```
 
 ## Defer a job if you can't access the task
 
 This is useful if the code that defers jobs is not in the same code base as the code
 that runs the jobs. You can defer a job with just the name of its task.
 
-```
+```python
 app.configure_task(name="my_module.my_task", queue="some_queue").defer(a=1, b=2)
+# or
+await app.configure_task(name="my_module.my_task", queue="some_queue").defer_async(a=1, b=2)
 ```
 
 Any parameter you would use for {py:meth}`Task.configure` can be used in

docs/howto/basics/tasks.md

@@ -1,22 +1,43 @@
 # Define a task
 
-You can specify a task with:
+Specify a sync task with:
 
-```
+```python
 @app.task(...)
 def mytask(argument, other_argument):
     ...
 ```
 
+:::{note}
+Each sync task runs in its own thread (independently of the worker thread).
+:::
+
+Or an async task with:
+
+```python
+@app.task(...)
+async def mytask(argument, other_argument):
+    ...
+```
+
+:::{note}
+All async tasks run in the same event loop.
+:::
+
 See {py:meth}`App.task` for the exact parameters. In particular, you can define values for
 `queue`, `lock` and  `queueing_lock` that will be used as default values when
 calling {py:meth}`Task.configure` or {py:meth}`Task.defer` on this task.
 
 If you're OK with all the default parameters, you can omit parentheses after
 `task`:
 
-```
+```python
 @app.task
 def mytask(argument, other_argument):
     ...
+
+# or
+@app.task
+async def mytask(argument, other_argument):
+    ...
 ```