[3.11] gh-86457: Add docs for Argument Clinic @text_signature directive (#107747...

(cherry picked from commit a9aeb99579f24bbce1dd553d605a5a5e2f37a3a2)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index d75ba8a19cff2e90c0c00c2a488ff06f9fafae1f..23be8a7a85c093e41f425b2972d923246516432a 100644 (file)
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -1893,3 +1893,36 @@ blocks embedded in Python files look slightly different.  They look like this:
     #[python start generated code]*/
     def foo(): pass
     #/*[python checksum:...]*/
+
+
+.. _clinic-howto-override-signature:
+
+How to override the generated signature
+---------------------------------------
+
+You can use the ``@text_signature`` directive to override the default generated
+signature in the docstring.
+This can be useful for complex signatures that Argument Clinic cannot handle.
+The ``@text_signature`` directive takes one argument:
+the custom signature as a string.
+The provided signature is copied verbatim to the generated docstring.
+
+Example from :source:`Objects/codeobject.c`::
+
+   /*[clinic input]
+   @text_signature "($self, /, **changes)"
+   code.replace
+       *
+       co_argcount: int(c_default="self->co_argcount") = unchanged
+       co_posonlyargcount: int(c_default="self->co_posonlyargcount") = unchanged
+       # etc ...
+
+       Return a copy of the code object with new values for the specified fields.
+   [clinic start generated output]*/
+
+The generated docstring ends up looking like this::
+
+   replace($self, /, **changes)
+   --
+
+   Return a copy of the code object with new values for the specified fields.

diff --git a/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst b/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst
index 4768e6767574d838be001055028a6311386b94ff..7284f5bd5488106061728be47cf7ad02856321ca 100644 (file)
--- a/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst
+++ b/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst
@@ -1,2 +1,2 @@
 Argument Clinic now supports overriding automatically generated signature by
-using directive ``@text_signature``.
+using directive ``@text_signature``. See :ref:`clinic-howto-override-signature`.