Docs: Normalise Argument Clinic advanced topics headings (pythonGH-10…

…6842)

(cherry picked from commit 4cb0b9c)

Co-authored-by: Erlend E. Aasland <erlend@python.org>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

Doc/howto/clinic.rst

@@ -560,15 +560,12 @@ Let's dive in!
     Congratulations, you've ported your first function to work with Argument Clinic!
 
 
-Advanced topics
-===============
+How-to guides
+=============
 
-Now that you've had some experience working with Argument Clinic, it's time
-for some advanced topics.
 
-
-Symbolic default values
------------------------
+How to use symbolic default values
+----------------------------------
 
 The default value you provide for a parameter can't be any arbitrary
 expression.  Currently the following are explicitly supported:
@@ -583,8 +580,8 @@ expression.  Currently the following are explicitly supported:
 to allow full expressions like ``CONSTANT - 1``.)
 
 
-Renaming the C functions and variables generated by Argument Clinic
--------------------------------------------------------------------
+How to to rename C functions and variables generated by Argument Clinic
+-----------------------------------------------------------------------
 
 Argument Clinic automatically names the functions it generates for you.
 Occasionally this may cause a problem, if the generated name collides with
@@ -626,8 +623,8 @@ array) would be ``file``, but the C variable would be named ``file_obj``.
 You can use this to rename the ``self`` parameter too!
 
 
-Converting functions using PyArg_UnpackTuple
---------------------------------------------
+How to convert functions using ``PyArg_UnpackTuple``
+----------------------------------------------------
 
 To convert a function parsing its arguments with :c:func:`PyArg_UnpackTuple`,
 simply write out all the arguments, specifying each as an ``object``.  You
@@ -639,8 +636,8 @@ Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this
 will change soon.
 
 
-Optional groups
----------------
+How to use optional groups
+--------------------------
 
 Some legacy functions have a tricky approach to parsing their arguments:
 they count the number of positional arguments, then use a ``switch`` statement
@@ -732,8 +729,8 @@ Notes:
   use optional groups for new code.
 
 
-Using real Argument Clinic converters, instead of "legacy converters"
----------------------------------------------------------------------
+How to use real Argument Clinic converters, instead of "legacy converters"
+--------------------------------------------------------------------------
 
 To save time, and to minimize how much you need to learn
 to achieve your first port to Argument Clinic, the walkthrough above tells
@@ -903,17 +900,17 @@ it accepts, along with the default value for each parameter.
 Just run ``Tools/clinic/clinic.py --converters`` to see the full list.
 
 
-Py_buffer
----------
+How to use the ``Py_buffer`` converter
+--------------------------------------
 
 When using the ``Py_buffer`` converter
 (or the ``'s*'``, ``'w*'``, ``'*y'``, or ``'z*'`` legacy converters),
 you *must* not call :c:func:`PyBuffer_Release` on the provided buffer.
 Argument Clinic generates code that does it for you (in the parsing function).
 
 
-Advanced converters
--------------------
+How to use advanced converters
+------------------------------
 
 Remember those format units you skipped for your first
 time because they were advanced?  Here's how to handle those too.
@@ -944,8 +941,8 @@ hard-coded encoding strings for parameters whose format units start with ``e``.
 
 .. _default_values:
 
-Parameter default values
-------------------------
+How to assign default values to parameter
+-----------------------------------------
 
 Default values for parameters can be any of a number of values.
 At their simplest, they can be string, int, or float literals:
@@ -968,8 +965,8 @@ There's also special support for a default value of ``NULL``, and
 for simple expressions, documented in the following sections.
 
 
-The ``NULL`` default value
---------------------------
+How to use the ``NULL`` default value
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For string and object parameters, you can set them to ``None`` to indicate
 that there's no default.  However, that means the C variable will be
@@ -979,8 +976,8 @@ behaves like a default value of ``None``, but the C variable is initialized
 with ``NULL``.
 
 
-Expressions specified as default values
----------------------------------------
+How to use expressions as default values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The default value for a parameter can be more than just a literal value.
 It can be an entire expression, using math operators and looking up attributes
@@ -1036,8 +1033,8 @@ you're not permitted to use:
 * Tuple/list/set/dict literals.
 
 
-Using a return converter
-------------------------
+How to use return converters
+----------------------------
 
 By default, the impl function Argument Clinic generates for you returns
 :c:type:`PyObject * <PyObject>`.
@@ -1106,8 +1103,8 @@ their parameters (if any),
 just run ``Tools/clinic/clinic.py --converters`` for the full list.
 
 
-Cloning existing functions
---------------------------
+How to clone existing functions
+-------------------------------
 
 If you have a number of functions that look similar, you may be able to
 use Clinic's "clone" feature.  When you clone an existing function,
@@ -1150,8 +1147,8 @@ Also, the function you are cloning from must have been previously defined
 in the current file.
 
 
-Calling Python code
--------------------
+How to call Python code
+-----------------------
 
 The rest of the advanced topics require you to write Python code
 which lives inside your C file and modifies Argument Clinic's
@@ -1178,8 +1175,8 @@ variable to the C code::
     /*[python checksum:...]*/
 
 
-Using a "self converter"
-------------------------
+How to use the "self converter"
+-------------------------------
 
 Argument Clinic automatically adds a "self" parameter for you
 using a default converter.  It automatically sets the ``type``
@@ -1230,8 +1227,8 @@ type for ``self``, it's best to create your own converter, subclassing
     [clinic start generated code]*/
 
 
-Using a "defining class" converter
-----------------------------------
+How to use the "defining class" converter
+-----------------------------------------
 
 Argument Clinic facilitates gaining access to the defining class of a method.
 This is useful for :ref:`heap type <heap-types>` methods that need to fetch
@@ -1293,8 +1290,8 @@ state.  Example from the ``setattro`` slot method in
 See also :pep:`573`.
 
 
-Writing a custom converter
---------------------------
+How to write a custom converter
+-------------------------------
 
 As we hinted at in the previous section... you can write your own converters!
 A converter is simply a Python class that inherits from ``CConverter``.
@@ -1385,8 +1382,8 @@ You can see more examples of custom converters in the CPython
 source tree; grep the C files for the string ``CConverter``.
 
 
-Writing a custom return converter
----------------------------------
+How to write a custom return converter
+--------------------------------------
 
 Writing a custom return converter is much like writing
 a custom converter.  Except it's somewhat simpler, because return
@@ -1400,8 +1397,8 @@ specifically the implementation of ``CReturnConverter`` and
 all its subclasses.
 
 
-METH_O and METH_NOARGS
-----------------------
+How to convert ``METH_O`` and ``METH_NOARGS`` functions
+-------------------------------------------------------
 
 To convert a function using ``METH_O``, make sure the function's
 single argument is using the ``object`` converter, and mark the
@@ -1422,8 +1419,8 @@ You can still use a self converter, a return converter, and specify
 a ``type`` argument to the object converter for ``METH_O``.
 
 
-tp_new and tp_init functions
-----------------------------
+How to convert ``tp_new`` and ``tp_init`` functions
+---------------------------------------------------
 
 You can convert ``tp_new`` and ``tp_init`` functions.  Just name
 them ``__new__`` or ``__init__`` as appropriate.  Notes:
@@ -1445,8 +1442,8 @@ them ``__new__`` or ``__init__`` as appropriate.  Notes:
   generated will throw an exception if it receives any.)
 
 
-Changing and redirecting Clinic's output
-----------------------------------------
+How to change and redirect Clinic's output
+------------------------------------------
 
 It can be inconvenient to have Clinic's output interspersed with
 your conventional hand-edited C code.  Luckily, Clinic is configurable:
@@ -1728,8 +1725,8 @@ it in a Clinic block lets Clinic use its existing checksum functionality to ensu
 the file was not modified by hand before it gets overwritten.
 
 
-The #ifdef trick
-----------------
+How to use the ``#ifdef`` trick
+-------------------------------
 
 If you're converting a function that isn't available on all platforms,
 there's a trick you can use to make life a little easier.  The existing
@@ -1809,8 +1806,8 @@ Argument Clinic added to your file (it'll be at the very bottom), then
 move it above the ``PyMethodDef`` structure where that macro is used.
 
 
-Using Argument Clinic in Python files
--------------------------------------
+How to use Argument Clinic in Python files
+------------------------------------------
 
 It's actually possible to use Argument Clinic to preprocess Python files.
 There's no point to using Argument Clinic blocks, of course, as the output