Skip to content

Commit c73f9c0

Browse files
[3.11] Docs: Normalize Argument Clinic How-To section capitalization (GH-106788) (#106792)
(cherry picked from commit 8c17729) Co-authored-by: Erlend E. Aasland <erlend@python.org>
1 parent 465f5b0 commit c73f9c0

File tree

1 file changed

+18
-11
lines changed

1 file changed

+18
-11
lines changed

Doc/howto/clinic.rst

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ Argument Clinic How-To
2727
version of Argument Clinic that ships with the next version
2828
of CPython *could* be totally incompatible and break all your code.
2929

30-
The Goals Of Argument Clinic
30+
31+
The goals of Argument Clinic
3132
============================
3233

3334
Argument Clinic's primary goal
@@ -78,7 +79,7 @@ and it should be able to do many interesting and smart
7879
things with all the information you give it.
7980

8081

81-
Basic Concepts And Usage
82+
Basic concepts and usage
8283
========================
8384

8485
Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``.
@@ -141,7 +142,7 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic:
141142
a block.)
142143

143144

144-
Converting Your First Function
145+
Converting your first function
145146
==============================
146147

147148
The best way to get a sense of how Argument Clinic works is to
@@ -550,7 +551,8 @@ Let's dive in!
550551

551552
Congratulations, you've ported your first function to work with Argument Clinic!
552553

553-
Advanced Topics
554+
555+
Advanced topics
554556
===============
555557

556558
Now that you've had some experience working with Argument Clinic, it's time
@@ -628,7 +630,8 @@ after the last argument).
628630
Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this
629631
will change soon.
630632

631-
Optional Groups
633+
634+
Optional groups
632635
---------------
633636

634637
Some legacy functions have a tricky approach to parsing their arguments:
@@ -888,6 +891,7 @@ available. For each converter it'll show you all the parameters
888891
it accepts, along with the default value for each parameter.
889892
Just run ``Tools/clinic/clinic.py --converters`` to see the full list.
890893

894+
891895
Py_buffer
892896
---------
893897

@@ -897,7 +901,6 @@ you *must* not call :c:func:`PyBuffer_Release` on the provided buffer.
897901
Argument Clinic generates code that does it for you (in the parsing function).
898902

899903

900-
901904
Advanced converters
902905
-------------------
903906

@@ -964,6 +967,7 @@ value called ``NULL`` for just this reason: from Python's perspective it
964967
behaves like a default value of ``None``, but the C variable is initialized
965968
with ``NULL``.
966969

970+
967971
Expressions specified as default values
968972
---------------------------------------
969973

@@ -1021,7 +1025,6 @@ you're not permitted to use:
10211025
* Tuple/list/set/dict literals.
10221026

10231027

1024-
10251028
Using a return converter
10261029
------------------------
10271030

@@ -1140,6 +1143,7 @@ then modifying it. Cloning is an all-or nothing proposition.
11401143
Also, the function you are cloning from must have been previously defined
11411144
in the current file.
11421145

1146+
11431147
Calling Python code
11441148
-------------------
11451149

@@ -1374,6 +1378,7 @@ handle initialization and cleanup.
13741378
You can see more examples of custom converters in the CPython
13751379
source tree; grep the C files for the string ``CConverter``.
13761380

1381+
13771382
Writing a custom return converter
13781383
---------------------------------
13791384

@@ -1388,8 +1393,9 @@ write your own return converter, please read ``Tools/clinic/clinic.py``,
13881393
specifically the implementation of ``CReturnConverter`` and
13891394
all its subclasses.
13901395

1396+
13911397
METH_O and METH_NOARGS
1392-
----------------------------------------------
1398+
----------------------
13931399

13941400
To convert a function using ``METH_O``, make sure the function's
13951401
single argument is using the ``object`` converter, and mark the
@@ -1409,8 +1415,9 @@ any arguments.
14091415
You can still use a self converter, a return converter, and specify
14101416
a ``type`` argument to the object converter for ``METH_O``.
14111417

1418+
14121419
tp_new and tp_init functions
1413-
----------------------------------------------
1420+
----------------------------
14141421

14151422
You can convert ``tp_new`` and ``tp_init`` functions. Just name
14161423
them ``__new__`` or ``__init__`` as appropriate. Notes:
@@ -1431,6 +1438,7 @@ them ``__new__`` or ``__init__`` as appropriate. Notes:
14311438
(If your function doesn't support keywords, the parsing function
14321439
generated will throw an exception if it receives any.)
14331440

1441+
14341442
Changing and redirecting Clinic's output
14351443
----------------------------------------
14361444

@@ -1715,7 +1723,7 @@ the file was not modified by hand before it gets overwritten.
17151723

17161724

17171725
The #ifdef trick
1718-
----------------------------------------------
1726+
----------------
17191727

17201728
If you're converting a function that isn't available on all platforms,
17211729
there's a trick you can use to make life a little easier. The existing
@@ -1795,7 +1803,6 @@ Argument Clinic added to your file (it'll be at the very bottom), then
17951803
move it above the ``PyMethodDef`` structure where that macro is used.
17961804

17971805

1798-
17991806
Using Argument Clinic in Python files
18001807
-------------------------------------
18011808

0 commit comments

Comments
 (0)