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

(cherry picked from commit a9aeb99)

Co-authored-by: Alex Waygood <[email protected]>

Author: erlend-aasland

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.

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`.