[Python-checkins] Docs: clean up Argument Clinic howto's (#107797)

[erlend-aasland]

https://github.com/python/cpython/commit/34cafd35e35dcb44b4347a6478fdbf88b900240c
commit: 34cafd35e35dcb44b4347a6478fdbf88b900240c
branch: main
author: Erlend E. Aasland <erlend at python.org>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-08-09T09:43:02+02:00
summary:

Docs: clean up Argument Clinic howto's (#107797)

- fix formatting in @text_signature howto and NEWS entry
- fix formatting and example text in deprecate-positionals howto

files:
M Doc/howto/clinic.rst
M Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 2d89ccc203b6d..463a938fafa8d 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -1930,13 +1930,14 @@ Example from :source:`Objects/codeobject.c`::
        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::
+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.");
+.. code-block:: none
+
+   replace($self, /, **changes)
+   --
+
+   Return a copy of the code object with new values for the specified fields.
 
 
 .. _clinic-howto-deprecate-positional:
@@ -1968,7 +1969,7 @@ whenever the *b* parameter is passed positionally,
 and we'll be allowed to make it keyword-only in Python 3.14 at the earliest.
 
 We can use Argument Clinic to emit the desired deprecation warnings
-using the ``* [from ...]``` syntax,
+using the ``* [from ...]`` syntax,
 by adding the line ``* [from 3.14]`` right above the *b* parameter::
 
    /*[clinic input]
@@ -2000,12 +2001,12 @@ Luckily for us, compiler warnings are now generated:
 .. code-block:: none
 
    In file included from Modules/foomodule.c:139:
-   Modules/clinic/foomodule.c.h:83:8: warning: Update 'b' in 'myfunc' in 'foomodule.c' to be keyword-only. [-W#warnings]
-    #    warning "Update 'b' in 'myfunc' in 'foomodule.c' to be keyword-only."
+   Modules/clinic/foomodule.c.h:139:8: warning: In 'foomodule.c', update parameter(s) 'a' and 'b' in the clinic input of 'mymod.myfunc' to be keyword-only. [-W#warnings]
+    #    warning "In 'foomodule.c', update parameter(s) 'a' and 'b' in the clinic input of 'mymod.myfunc' to be keyword-only. [-W#warnings]"
          ^
 
 We now close the deprecation phase by making *b* keyword-only;
-replace the ``* [from ...]``` line above *b*
+replace the ``* [from ...]`` line above *b*
 with the ``*`` from the line above *c*::
 
    /*[clinic input]
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 df1893e9c808e..7284f5bd54881 100644
--- 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`. See :ref:`clinic-howto-override-signature`.
+using directive ``@text_signature``. See :ref:`clinic-howto-override-signature`.