Update the 'Python Signatures' section

doc/usage/domains/python.rst

@@ -563,35 +563,46 @@ Python Signatures
 
 Signatures of functions, methods and class constructors can be given like they
 would be written in Python.
+This can include default values, positional-only or keyword-only parameters,
+type annotations, and type parameters.
+For example:
 
-Default values for optional arguments can be given (but if they contain commas,
-they will confuse the signature parser).  Python 3-style argument annotations
-can also be given as well as return type annotations::
+.. code-block:: rst
 
-   .. py:function:: compile(source : string, filename, symbol='file') -> ast object
+   .. py:function:: compile(source: str, filename: Path, symbol: str = 'file') -> ast.AST
+
+.. py:function:: compile(source: str, filename: Path, symbol: str = 'file') -> ast.AST
+   :no-index:
 
 For functions with optional parameters that don't have default values
 (typically functions implemented in C extension modules without keyword
-argument support), you can use brackets to specify the optional parts:
+argument support),
+you can list multiple versions of the same signature in a single directive:
+
+.. py:function:: compile(source)
+                 compile(source, filename)
+                 compile(source, filename, symbol)
+   :no-index:
+
+Another approach is to use square brackets to specify the optional parts.
+When using square brackets, it is customary to place
+the opening bracket before the comma (``[,``).
 
 .. py:function:: compile(source[, filename[, symbol]])
-   :no-contents-entry:
-   :no-index-entry:
-
-It is customary to put the opening bracket before the comma.
+   :no-index:
 
 Python 3.12 introduced *type parameters*, which are type variables
-declared directly  within the class or function definition:
+declared directly within the class or function definition:
 
 .. code-block:: python
 
    class AnimalList[AnimalT](list[AnimalT]):
-      ...
+       ...
 
    def add[T](a: T, b: T) -> T:
-      return a + b
+       return a + b
 
-The corresponding reStructuredText documentation would be:
+The corresponding reStructuredText markup would be:
 
 .. code-block:: rst
 
@@ -599,7 +610,10 @@ The corresponding reStructuredText documentation would be:
 
    .. py:function:: add[T](a: T, b: T) -> T
 
-See :pep:`695` and :pep:`696` for details and the full specification.
+.. seealso::
+
+   :pep:`695` and :pep:`696`, for details and the full specification.
+
 
 .. _info-field-lists: