From 44891a4eefabf64067bb4903a69be84b1974094f Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sun, 26 Jan 2025 04:54:34 +0000
Subject: [PATCH] Update the 'Python Signatures' section

---
 doc/usage/domains/python.rst | 42 ++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 14 deletions(-)

diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst
index 8020aae41c6..33cf2b25297 100644
--- a/doc/usage/domains/python.rst
+++ b/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: str, filename: Path, symbol: str = 'file') -> ast.AST
 
-   .. py:function:: compile(source : string, filename, symbol='file') -> ast object
+.. 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[, filename[, symbol]])
-   :no-contents-entry:
-   :no-index-entry:
+.. py:function:: compile(source)
+                 compile(source, filename)
+                 compile(source, filename, symbol)
+   :no-index:
 
-It is customary to put the opening bracket before the comma.
+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-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: