Docs: Add missing markup to Argument Clinic docs (#106876)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

1 files changed, 143 insertions, 126 deletions

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 933feca..98d3632 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -96,7 +96,8 @@ things with all the information you give it.
 Basic concepts and usage
 ------------------------
 
-Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``.
+Argument Clinic ships with CPython; you'll find it in
+:source:`Tools/clinic/clinic.py`.
 If you run that script, specifying a C file as an argument:
 
 .. code-block:: shell-session
@@ -178,9 +179,10 @@ Let's dive in!
 1. Find a Python builtin that calls either :c:func:`PyArg_ParseTuple`
    or :c:func:`PyArg_ParseTupleAndKeywords`, and hasn't been converted
    to work with Argument Clinic yet.
-   For my example I'm using ``_pickle.Pickler.dump()``.
+   For my example I'm using
+   :py:meth:`_pickle.Pickler.dump <pickle.Pickler.dump>`.
 
-2. If the call to the ``PyArg_Parse`` function uses any of the
+2. If the call to the :c:func:`!PyArg_Parse*` function uses any of the
    following format units:
 
    .. code-block:: none
@@ -197,10 +199,10 @@ Let's dive in!
    support all of these scenarios.  But these are advanced
    topics—let's do something simpler for your first function.
 
-   Also, if the function has multiple calls to :c:func:`PyArg_ParseTuple`
+   Also, if the function has multiple calls to :c:func:`!PyArg_ParseTuple`
    or :c:func:`PyArg_ParseTupleAndKeywords` where it supports different
    types for the same argument, or if the function uses something besides
-   PyArg_Parse functions to parse its arguments, it probably
+   :c:func:`!PyArg_Parse*` functions to parse its arguments, it probably
    isn't suitable for conversion to Argument Clinic.  Argument Clinic
    doesn't support generic functions or polymorphic parameters.
 
@@ -217,7 +219,7 @@ Let's dive in!
 
    If the old docstring had a first line that looked like a function
    signature, throw that line away.  (The docstring doesn't need it
-   anymore—when you use ``help()`` on your builtin in the future,
+   anymore—when you use :py:func:`help` on your builtin in the future,
    the first line will be built automatically based on the function's
    signature.)
 
@@ -264,7 +266,7 @@ Let's dive in!
 
    When you declare a class, you must also specify two aspects of its type
    in C: the type declaration you'd use for a pointer to an instance of
-   this class, and a pointer to the :c:type:`PyTypeObject` for this class.
+   this class, and a pointer to the :c:type:`!PyTypeObject` for this class.
 
    Sample::
 
@@ -313,10 +315,10 @@ Let's dive in!
    Clinic easier.
 
    For each parameter, copy the "format unit" for that
-   parameter from the ``PyArg_Parse()`` format argument and
+   parameter from the :c:func:`PyArg_Parse` format argument and
    specify *that* as its converter, as a quoted
    string.  ("format unit" is the formal name for the one-to-three
-   character substring of the ``format`` parameter that tells
+   character substring of the *format* parameter that tells
    the argument parsing function what the type of the variable
    is and how to convert it.  For more on format units please
    see :ref:`arg-parsing`.)
@@ -349,7 +351,7 @@ Let's dive in!
    itself before the first keyword-only argument, indented the
    same as the parameter lines.
 
-   (``_pickle.Pickler.dump`` has neither, so our sample is unchanged.)
+   (:py:meth:`!_pickle.Pickler.dump` has neither, so our sample is unchanged.)
 
 
 10. If the existing C function calls :c:func:`PyArg_ParseTuple`
@@ -410,7 +412,7 @@ Let's dive in!
 
 12. Save and close the file, then run ``Tools/clinic/clinic.py`` on
     it.  With luck everything worked---your block now has output, and
-    a ``.c.h`` file has been generated! Reopen the file in your
+    a :file:`.c.h` file has been generated! Reopen the file in your
     text editor to see::
 
        /*[clinic input]
@@ -431,8 +433,8 @@ Let's dive in!
     it found an error in your input.  Keep fixing your errors and retrying
     until Argument Clinic processes your file without complaint.
 
-    For readability, most of the glue code has been generated to a ``.c.h``
-    file.  You'll need to include that in your original ``.c`` file,
+    For readability, most of the glue code has been generated to a :file:`.c.h`
+    file.  You'll need to include that in your original :file:`.c` file,
     typically right after the clinic module block::
 
        #include "clinic/_pickle.c.h"
@@ -446,8 +448,8 @@ Let's dive in!
     ensure that the code generated by Argument Clinic calls the
     *exact* same function.
 
-    Second, the format string passed in to :c:func:`PyArg_ParseTuple` or
-    :c:func:`PyArg_ParseTupleAndKeywords` should be *exactly* the same
+    Second, the format string passed in to :c:func:`!PyArg_ParseTuple` or
+    :c:func:`!PyArg_ParseTupleAndKeywords` should be *exactly* the same
     as the hand-written one in the existing function, up to the colon
     or semi-colon.
 
@@ -469,7 +471,7 @@ Let's dive in!
         {"dump", (PyCFunction)__pickle_Pickler_dump, METH_O, __pickle_Pickler_dump__doc__},
 
     This static structure should be *exactly* the same as the existing static
-    :c:type:`PyMethodDef` structure for this builtin.
+    :c:type:`!PyMethodDef` structure for this builtin.
 
     If any of these items differ in *any way*,
     adjust your Argument Clinic function specification and rerun
@@ -539,14 +541,14 @@ Let's dive in!
             ...
 
 15. Remember the macro with the :c:type:`PyMethodDef` structure for this
-    function?  Find the existing :c:type:`PyMethodDef` structure for this
+    function?  Find the existing :c:type:`!PyMethodDef` structure for this
     function and replace it with a reference to the macro.  (If the builtin
     is at module scope, this will probably be very near the end of the file;
     if the builtin is a class method, this will probably be below but relatively
     near to the implementation.)
 
     Note that the body of the macro contains a trailing comma.  So when you
-    replace the existing static :c:type:`PyMethodDef` structure with the macro,
+    replace the existing static :c:type:`!PyMethodDef` structure with the macro,
     *don't* add a comma to the end.
 
     Sample::
@@ -562,7 +564,7 @@ Let's dive in!
 
         &_Py_ID(new_unique_py_id)
 
-    If it does, you'll have to run ``Tools/scripts/generate_global_objects.py``
+    If it does, you'll have to run ``make regen-global-objects``
     to regenerate the list of precompiled identifiers at this point.
 
 
@@ -570,7 +572,7 @@ Let's dive in!
     This change should not introduce any new compile-time warnings or errors,
     and there should be no externally visible change to Python's behavior.
 
-    Well, except for one difference: ``inspect.signature()`` run on your function
+    Well, except for one difference: :py:func:`inspect.signature` run on your function
     should now provide a valid signature!
 
     Congratulations, you've ported your first function to work with Argument Clinic!
@@ -594,15 +596,15 @@ Argument Clinic will use that function name for the base (generated) function,
 then add ``"_impl"`` to the end and use that for the name of the impl function.
 
 For example, if we wanted to rename the C function names generated for
-``pickle.Pickler.dump``, it'd look like this::
+:py:meth:`pickle.Pickler.dump`, it'd look like this::
 
     /*[clinic input]
     pickle.Pickler.dump as pickler_dumper
 
     ...
 
-The base function would now be named ``pickler_dumper()``,
-and the impl function would now be named ``pickler_dumper_impl()``.
+The base function would now be named :c:func:`!pickler_dumper`,
+and the impl function would now be named :c:func:`!pickler_dumper_impl`.
 
 
 Similarly, you may have a problem where you want to give a parameter
@@ -620,9 +622,9 @@ using the same ``"as"`` syntax::
         fix_imports: bool = True
 
 Here, the name used in Python (in the signature and the ``keywords``
-array) would be ``file``, but the C variable would be named ``file_obj``.
+array) would be *file*, but the C variable would be named ``file_obj``.
 
-You can use this to rename the ``self`` parameter too!
+You can use this to rename the *self* parameter too!
 
 
 How to convert functions using ``PyArg_UnpackTuple``
@@ -630,7 +632,7 @@ 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
-may specify the ``type`` argument to cast the type as appropriate.  All
+may specify the *type* argument to cast the type as appropriate.  All
 arguments should be marked positional-only (add a ``/`` on a line by itself
 after the last argument).
 
@@ -649,16 +651,16 @@ keyword-only arguments.)  This approach was used to simulate optional
 arguments back before :c:func:`PyArg_ParseTupleAndKeywords` was created.
 
 While functions using this approach can often be converted to
-use :c:func:`PyArg_ParseTupleAndKeywords`, optional arguments, and default values,
+use :c:func:`!PyArg_ParseTupleAndKeywords`, optional arguments, and default values,
 it's not always possible.  Some of these legacy functions have
-behaviors :c:func:`PyArg_ParseTupleAndKeywords` doesn't directly support.
-The most obvious example is the builtin function ``range()``, which has
+behaviors :c:func:`!PyArg_ParseTupleAndKeywords` doesn't directly support.
+The most obvious example is the builtin function :py:func:`range`, which has
 an optional argument on the *left* side of its required argument!
-Another example is ``curses.window.addch()``, which has a group of two
+Another example is :py:meth:`curses.window.addch`, which has a group of two
 arguments that must always be specified together.  (The arguments are
-called ``x`` and ``y``; if you call the function passing in ``x``,
-you must also pass in ``y``—and if you don't pass in ``x`` you may not
-pass in ``y`` either.)
+called *x* and *y*; if you call the function passing in *x*,
+you must also pass in *y* — and if you don't pass in *x* you may not
+pass in *y* either.)
 
 In any case, the goal of Argument Clinic is to support argument parsing
 for all existing CPython builtins without changing their semantics.
@@ -679,7 +681,7 @@ can *only* be used with positional-only parameters.
 
 To specify an optional group, add a ``[`` on a line by itself before
 the parameters you wish to group together, and a ``]`` on a line by itself
-after these parameters.  As an example, here's how ``curses.window.addch``
+after these parameters.  As an example, here's how :py:meth:`curses.window.addch`
 uses optional groups to make the first two parameters and the last
 parameter optional::
 
@@ -765,25 +767,25 @@ the same converters.
 All arguments to Argument Clinic converters are keyword-only.
 All Argument Clinic converters accept the following arguments:
 
-  ``c_default``
+  *c_default*
     The default value for this parameter when defined in C.
     Specifically, this will be the initializer for the variable declared
     in the "parse function".  See :ref:`the section on default values <default_values>`
     for how to use this.
     Specified as a string.
 
-  ``annotation``
+  *annotation*
     The annotation value for this parameter.  Not currently supported,
     because :pep:`8` mandates that the Python library may not use
     annotations.
 
-  ``unused``
+  *unused*
     Wrap the argument with :c:macro:`Py_UNUSED` in the impl function signature.
 
 In addition, some converters accept additional arguments.  Here is a list
 of these arguments, along with their meanings:
 
-  ``accept``
+  *accept*
     A set of Python types (and possibly pseudo-types);
     this restricts the allowable Python argument to values of these types.
     (This is not a general-purpose facility; as a rule it only supports
@@ -791,38 +793,38 @@ of these arguments, along with their meanings:
 
     To accept ``None``, add ``NoneType`` to this set.
 
-  ``bitwise``
+  *bitwise*
     Only supported for unsigned integers.  The native integer value of this
     Python argument will be written to the parameter without any range checking,
     even for negative values.
 
-  ``converter``
+  *converter*
     Only supported by the ``object`` converter.  Specifies the name of a
     :ref:`C "converter function" <o_ampersand>`
     to use to convert this object to a native type.
 
-  ``encoding``
+  *encoding*
     Only supported for strings.  Specifies the encoding to use when converting
     this string from a Python str (Unicode) value into a C ``char *`` value.
 
 
-  ``subclass_of``
+  *subclass_of*
     Only supported for the ``object`` converter.  Requires that the Python
     value be a subclass of a Python type, as expressed in C.
 
-  ``type``
+  *type*
     Only supported for the ``object`` and ``self`` converters.  Specifies
     the C type that will be used to declare the variable.  Default value is
     ``"PyObject *"``.
 
-  ``zeroes``
+  *zeroes*
     Only supported for strings.  If true, embedded NUL bytes (``'\\0'``) are
     permitted inside the value.  The length of the string will be passed in
     to the impl function, just after the string parameter, as a parameter named
     ``<parameter_name>_length``.
 
 Please note, not every possible combination of arguments will work.
-Usually these arguments are implemented by specific ``PyArg_ParseTuple``
+Usually these arguments are implemented by specific :c:func:`PyArg_ParseTuple`
 *format units*, with specific behavior.  For example, currently you cannot
 call ``unsigned_short`` without also specifying ``bitwise=True``.
 Although it's perfectly reasonable to think this would work, these semantics don't
@@ -922,19 +924,19 @@ conversion functions, or types, or strings specifying an encoding.
 (But "legacy converters" don't support arguments.  That's why we
 skipped them for your first function.)  The argument you specified
 to the format unit is now an argument to the converter; this
-argument is either ``converter`` (for ``O&``), ``subclass_of`` (for ``O!``),
-or ``encoding`` (for all the format units that start with ``e``).
+argument is either *converter* (for ``O&``), *subclass_of* (for ``O!``),
+or *encoding* (for all the format units that start with ``e``).
 
-When using ``subclass_of``, you may also want to use the other
-custom argument for ``object()``: ``type``, which lets you set the type
+When using *subclass_of*, you may also want to use the other
+custom argument for ``object()``: *type*, which lets you set the type
 actually used for the parameter.  For example, if you want to ensure
-that the object is a subclass of ``PyUnicode_Type``, you probably want
+that the object is a subclass of :c:var:`PyUnicode_Type`, you probably want
 to use the converter ``object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type')``.
 
 One possible problem with using Argument Clinic: it takes away some possible
 flexibility for the format units starting with ``e``.  When writing a
-``PyArg_Parse`` call by hand, you could theoretically decide at runtime what
-encoding string to pass in to :c:func:`PyArg_ParseTuple`.   But now this string must
+:c:func:`!PyArg_Parse*` call by hand, you could theoretically decide at runtime what
+encoding string to pass to that call.   But now this string must
 be hard-coded at Argument-Clinic-preprocessing-time.  This limitation is deliberate;
 it made supporting this format unit much easier, and may allow for future optimizations.
 This restriction doesn't seem unreasonable; CPython itself always passes in static
@@ -987,7 +989,7 @@ expression.  Currently the following are explicitly supported:
 * Numeric constants (integer and float)
 * String constants
 * ``True``, ``False``, and ``None``
-* Simple symbolic constants like ``sys.maxsize``, which must
+* Simple symbolic constants like :py:data:`sys.maxsize`, which must
   start with the name of the module
 
 (In the future, this may need to get even more elaborate,
@@ -1008,28 +1010,28 @@ Consider the following example:
 
     foo: Py_ssize_t = sys.maxsize - 1
 
-``sys.maxsize`` can have different values on different platforms.  Therefore
+:py:data:`sys.maxsize` can have different values on different platforms.  Therefore
 Argument Clinic can't simply evaluate that expression locally and hard-code it
 in C.  So it stores the default in such a way that it will get evaluated at
 runtime, when the user asks for the function's signature.
 
 What namespace is available when the expression is evaluated?  It's evaluated
 in the context of the module the builtin came from.  So, if your module has an
-attribute called "``max_widgets``", you may simply use it:
+attribute called :py:attr:`!max_widgets`, you may simply use it:
 
 .. code-block:: none
 
     foo: Py_ssize_t = max_widgets
 
 If the symbol isn't found in the current module, it fails over to looking in
-``sys.modules``.  That's how it can find ``sys.maxsize`` for example.  (Since you
-don't know in advance what modules the user will load into their interpreter,
+:py:data:`sys.modules`.  That's how it can find :py:data:`sys.maxsize` for example.
+(Since you don't know in advance what modules the user will load into their interpreter,
 it's best to restrict yourself to modules that are preloaded by Python itself.)
 
 Evaluating default values only at runtime means Argument Clinic can't compute
 the correct equivalent C default value.  So you need to tell it explicitly.
 When you use an expression, you must also specify the equivalent expression
-in C, using the ``c_default`` parameter to the converter:
+in C, using the *c_default* parameter to the converter:
 
 .. code-block:: none
 
@@ -1095,7 +1097,7 @@ indicate an error has occurred?  Normally, a function returns a valid (non-``NUL
 pointer for success, and ``NULL`` for failure.  But if you use an integer return converter,
 all integers are valid.  How can Argument Clinic detect an error?  Its solution: each return
 converter implicitly looks for a special value that indicates an error.  If you return
-that value, and an error has been set (``PyErr_Occurred()`` returns a true
+that value, and an error has been set (c:func:`PyErr_Occurred` returns a true
 value), then the generated code will propagate the error.  Otherwise it will
 encode the value you return like normal.
 
@@ -1201,9 +1203,9 @@ using a default converter.  It automatically sets the ``type``
 of this parameter to the "pointer to an instance" you specified
 when you declared the type.  However, you can override
 Argument Clinic's converter and specify one yourself.
-Just add your own ``self`` parameter as the first parameter in a
+Just add your own *self* parameter as the first parameter in a
 block, and ensure that its converter is an instance of
-``self_converter`` or a subclass thereof.
+:class:`!self_converter` or a subclass thereof.
 
 What's the point?  This lets you override the type of ``self``,
 or give it a different default name.
@@ -1211,7 +1213,7 @@ or give it a different default name.
 How do you specify the custom type you want to cast ``self`` to?
 If you only have one or two functions with the same type for ``self``,
 you can directly use Argument Clinic's existing ``self`` converter,
-passing in the type you want to use as the ``type`` parameter::
+passing in the type you want to use as the *type* parameter::
 
     /*[clinic input]
 
@@ -1226,7 +1228,7 @@ passing in the type you want to use as the ``type`` parameter::
 
 On the other hand, if you have a lot of functions that will use the same
 type for ``self``, it's best to create your own converter, subclassing
-``self_converter`` but overwriting the ``type`` member::
+:class:`!self_converter` but overwriting the :py:attr:`!type` member::
 
     /*[python input]
     class PicklerObject_converter(self_converter):
@@ -1254,8 +1256,8 @@ module level state.  Use :c:func:`PyType_FromModuleAndSpec` to associate a new
 heap type with a module.  You can now use :c:func:`PyType_GetModuleState` on
 the defining class to fetch the module state, for example from a module method.
 
-Example from ``Modules/zlibmodule.c``.  First, ``defining_class`` is added to
-the clinic input::
+Example from :source:`Modules/zlibmodule.c`.
+First, ``defining_class`` is added to the clinic input::
 
     /*[clinic input]
     zlib.Compress.compress
@@ -1285,16 +1287,17 @@ module state::
 Each method may only have one argument using this converter, and it must appear
 after ``self``, or, if ``self`` is not used, as the first argument.  The argument
 will be of type ``PyTypeObject *``.  The argument will not appear in the
-``__text_signature__``.
+:py:attr:`!__text_signature__`.
 
-The ``defining_class`` converter is not compatible with ``__init__`` and ``__new__``
-methods, which cannot use the ``METH_METHOD`` convention.
+The ``defining_class`` converter is not compatible with :py:meth:`!__init__`
+and :py:meth:`!__new__` methods, which cannot use the :c:macro:`METH_METHOD`
+convention.
 
 It is not possible to use ``defining_class`` with slot methods.  In order to
 fetch the module state from such methods, use :c:func:`PyType_GetModuleByDef`
 to look up the module and then :c:func:`PyModule_GetState` to fetch the module
 state.  Example from the ``setattro`` slot method in
-``Modules/_threadmodule.c``::
+:source:`Modules/_threadmodule.c`::
 
     static int
     local_setattro(localobject *self, PyObject *name, PyObject *v)
@@ -1312,7 +1315,7 @@ 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``.
+A converter is simply a Python class that inherits from :py:class:`!CConverter`.
 The main purpose of a custom converter is if you have a parameter using
 the ``O&`` format unit—parsing this parameter means calling
 a :c:func:`PyArg_ParseTuple` "converter function".
@@ -1323,61 +1326,74 @@ will be automatically registered with Argument Clinic; its name
 will be the name of your class with the ``_converter`` suffix
 stripped off.  (This is accomplished with a metaclass.)
 
-You shouldn't subclass ``CConverter.__init__``.  Instead, you should
-write a ``converter_init()`` function.  ``converter_init()``
-always accepts a ``self`` parameter; after that, all additional
+You shouldn't subclass :py:meth:`!CConverter.__init__`.  Instead, you should
+write a :py:meth:`!converter_init` function. :py:meth:`!converter_init`
+always accepts a *self* parameter; after that, all additional
 parameters *must* be keyword-only.  Any arguments passed in to
 the converter in Argument Clinic will be passed along to your
-``converter_init()``.
+:py:meth:`!converter_init`.
 
-There are some additional members of ``CConverter`` you may wish
+There are some additional members of :py:class:`!CConverter` you may wish
 to specify in your subclass.  Here's the current list:
 
-``type``
-    The C type to use for this variable.
-    ``type`` should be a Python string specifying the type, e.g. ``int``.
-    If this is a pointer type, the type string should end with ``' *'``.
+.. module:: clinic
 
-``default``
-    The Python default value for this parameter, as a Python value.
-    Or the magic value ``unspecified`` if there is no default.
+.. class:: CConverter
 
-``py_default``
-    ``default`` as it should appear in Python code,
-    as a string.
-    Or ``None`` if there is no default.
+   .. attribute:: type
 
-``c_default``
-    ``default`` as it should appear in C code,
-    as a string.
-    Or ``None`` if there is no default.
+      The C type to use for this variable.
+      :attr:`!type` should be a Python string specifying the type,
+      e.g. ``'int'``.
+      If this is a pointer type, the type string should end with ``' *'``.
 
-``c_ignored_default``
-    The default value used to initialize the C variable when
-    there is no default, but not specifying a default may
-    result in an "uninitialized variable" warning.  This can
-    easily happen when using option groups—although
-    properly written code will never actually use this value,
-    the variable does get passed in to the impl, and the
-    C compiler will complain about the "use" of the
-    uninitialized value.  This value should always be a
-    non-empty string.
+   .. attribute:: default
 
-``converter``
-    The name of the C converter function, as a string.
+      The Python default value for this parameter, as a Python value.
+      Or the magic value ``unspecified`` if there is no default.
 
-``impl_by_reference``
-    A boolean value.  If true,
-    Argument Clinic will add a ``&`` in front of the name of
-    the variable when passing it into the impl function.
+   .. attribute:: py_default
 
-``parse_by_reference``
-    A boolean value.  If true,
-    Argument Clinic will add a ``&`` in front of the name of
-    the variable when passing it into :c:func:`PyArg_ParseTuple`.
+      :attr:`!default` as it should appear in Python code,
+      as a string.
+      Or ``None`` if there is no default.
 
+   .. attribute:: c_default
 
-Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c``::
+      :attr:`!default` as it should appear in C code,
+      as a string.
+      Or ``None`` if there is no default.
+
+   .. attribute:: c_ignored_default
+
+      The default value used to initialize the C variable when
+      there is no default, but not specifying a default may
+      result in an "uninitialized variable" warning.  This can
+      easily happen when using option groups—although
+      properly written code will never actually use this value,
+      the variable does get passed in to the impl, and the
+      C compiler will complain about the "use" of the
+      uninitialized value.  This value should always be a
+      non-empty string.
+
+   .. attribute:: converter
+
+      The name of the C converter function, as a string.
+
+   .. attribute:: impl_by_reference
+
+      A boolean value.  If true,
+      Argument Clinic will add a ``&`` in front of the name of
+      the variable when passing it into the impl function.
+
+   .. attribute:: parse_by_reference
+
+      A boolean value.  If true,
+      Argument Clinic will add a ``&`` in front of the name of
+      the variable when passing it into :c:func:`PyArg_ParseTuple`.
+
+
+Here's the simplest example of a custom converter, from :source:`Modules/zlibmodule.c`::
 
     /*[python input]
 
@@ -1397,7 +1413,7 @@ automatically support default values.
 More sophisticated custom converters can insert custom C code to
 handle initialization and cleanup.
 You can see more examples of custom converters in the CPython
-source tree; grep the C files for the string ``CConverter``.
+source tree; grep the C files for the string :py:class:`!CConverter`.
 
 
 How to write a custom return converter
@@ -1407,18 +1423,18 @@ Writing a custom return converter is much like writing
 a custom converter.  Except it's somewhat simpler, because return
 converters are themselves much simpler.
 
-Return converters must subclass ``CReturnConverter``.
+Return converters must subclass :py:class:`!CReturnConverter`.
 There are no examples yet of custom return converters,
 because they are not widely used yet.  If you wish to
-write your own return converter, please read ``Tools/clinic/clinic.py``,
-specifically the implementation of ``CReturnConverter`` and
+write your own return converter, please read :source:`Tools/clinic/clinic.py`,
+specifically the implementation of :py:class:`!CReturnConverter` and
 all its subclasses.
 
 
 How to convert ``METH_O`` and ``METH_NOARGS`` functions
 -------------------------------------------------------
 
-To convert a function using ``METH_O``, make sure the function's
+To convert a function using :c:macro:`METH_O`, make sure the function's
 single argument is using the ``object`` converter, and mark the
 arguments as positional-only::
 
@@ -1430,24 +1446,25 @@ arguments as positional-only::
     [clinic start generated code]*/
 
 
-To convert a function using ``METH_NOARGS``, just don't specify
+To convert a function using :c:macro:`METH_NOARGS`, just don't specify
 any arguments.
 
 You can still use a self converter, a return converter, and specify
-a ``type`` argument to the object converter for ``METH_O``.
+a *type* argument to the object converter for :c:macro:`METH_O`.
 
 
 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:
+You can convert :c:member:`~PyTypeObject.tp_new` and
+:c:member:`~PyTypeObject.tp_init` functions.
+Just name them ``__new__`` or ``__init__`` as appropriate.  Notes:
 
 * The function name generated for ``__new__`` doesn't end in ``__new__``
   like it would by default.  It's just the name of the class, converted
   into a valid C identifier.
 
-* No ``PyMethodDef`` ``#define`` is generated for these functions.
+* No :c:type:`PyMethodDef` ``#define`` is generated for these functions.
 
 * ``__init__`` functions return ``int``, not ``PyObject *``.
 
@@ -1482,7 +1499,7 @@ Let's start with defining some terminology:
 
 *field*
   A field, in this context, is a subsection of Clinic's output.
-  For example, the ``#define`` for the ``PyMethodDef`` structure
+  For example, the ``#define`` for the :c:type:`PyMethodDef` structure
   is a field, called ``methoddef_define``.  Clinic has seven
   different fields it can output per function definition:
 
@@ -1526,8 +1543,8 @@ Let's start with defining some terminology:
     The filename chosen for the file is ``{basename}.clinic{extension}``,
     where ``basename`` and ``extension`` were assigned the output
     from ``os.path.splitext()`` run on the current file.  (Example:
-    the ``file`` destination for ``_pickle.c`` would be written to
-    ``_pickle.clinic.c``.)
+    the ``file`` destination for :file:`_pickle.c` would be written to
+    :file:`_pickle.clinic.c`.)
 
     **Important: When using a** ``file`` **destination, you**
     *must check in* **the generated file!**
@@ -1780,7 +1797,7 @@ like so::
     }
     #endif /* HAVE_FUNCTIONNAME */
 
-Then, remove those three lines from the ``PyMethodDef`` structure,
+Then, remove those three lines from the :c:type:`PyMethodDef` structure,
 replacing them with the macro Argument Clinic generated:
 
 .. code-block:: none
@@ -1821,7 +1838,7 @@ This may mean that you get a complaint from Argument Clinic:
 
 When this happens, just open your file, find the ``dump buffer`` block that
 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.
+move it above the :c:type:`PyMethodDef` structure where that macro is used.
 
 
 How to use Argument Clinic in Python files