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

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

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 286623c24101457f97ca9af2e08b09bc0cc030c4..743c7c9cb3000ebbd11b3de4faafd87083955bf7 100644 (file)
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -1900,6 +1900,40 @@ blocks embedded in Python files look slightly different.  They look like this:
     #/*[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::
+
+   Doc_STRVAR(code_replace__doc__,
+   "replace($self, /, **changes)\n"
+   "--\n"
+   "\n"
+   "Return a copy of the code object with new values for the specified fields.");
+
+
 .. _clinic-howto-deprecate-positional:
 
 How to deprecate passing parameters positionally

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 41cfd72cb367605904050959d0509dd8cae6a258..df1893e9c808ef5d0d822d3d0765c2078af4736f 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`.