Add example event handler and decorator type annotations

docs/usage.rst

@@ -95,7 +95,7 @@ Programs
 Docstring processing
 --------------------
 
-sphinx-click provides the following additional events:
+*sphinx-click* provides the following additional events:
 
 .. py:function:: sphinx-click-process-description(app, ctx, lines)
 .. py:function:: sphinx-click-process-usage(app, ctx, lines)
@@ -111,7 +111,17 @@ sphinx-click provides the following additional events:
 Events are emitted when sphinx-click has read and processed part of a
 command's documentation. *lines* is a list of strings -- the lines of the
 documentation that was processed -- that the event handler can
-modify **in place** to change what Sphinx puts into the output
+modify **in place** to change what Sphinx puts into the output.
+
+.. code-block:: python
+
+    def process_description(app, ctx, lines):
+        """Append some text to the "example" command description."""
+        if ctx.command.name == "example":
+            lines.extend(["Hello, World!", ""])
+
+    def setup(app):
+        app.connect("sphinx-click-process-description", process_description)
 
 
 Example

sphinx_click/ext.py

@@ -1,4 +1,5 @@
 import inspect
+import functools
 import re
 import traceback
 import typing as ty
@@ -24,10 +25,13 @@
 
 ANSI_ESC_SEQ_RE = re.compile(r'\x1B\[\d+(;\d+){0,2}m', flags=re.MULTILINE)
 
+_T_Formatter = ty.Callable[[click.Context], ty.Generator[str, None, None]]
 
-def _process_lines(event_name):
-    def decorator(func):
-        def process_lines(ctx):
+
+def _process_lines(event_name: str) -> ty.Callable[[_T_Formatter], _T_Formatter]:
+    def decorator(func: _T_Formatter) -> _T_Formatter:
+        @functools.wraps(func)
+        def process_lines(ctx: click.Context) -> ty.Generator[str, None, None]:
             lines = list(func(ctx))
             if "sphinx-click-env" in ctx.meta:
                 ctx.meta["sphinx-click-env"].app.events.emit(