Skip to content

Commit 4baaf76

Browse files
Adapt clinic.rst
- Use ``:cpy-file:`` instead of ``:source:`` - Fix Sphinx complaint about 'range' - Mark up the abstract similar to other pages in the devguide
1 parent 7ef9a8e commit 4baaf76

File tree

1 file changed

+21
-27
lines changed

1 file changed

+21
-27
lines changed

development-tools/clinic.rst

+21-27
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,26 @@
11
.. highlight:: c
22

3-
.. _howto-clinic:
3+
.. _clinic:
44

5-
**********************
6-
Argument Clinic How-To
7-
**********************
5+
***************
6+
Argument Clinic
7+
***************
88

99
:author: Larry Hastings
1010

11-
**Source code:** :source:`Tools/clinic/clinic.py`.
11+
**Source code:** :cpy-file:`Tools/clinic/clinic.py`.
1212

13-
.. topic:: Abstract
13+
Argument Clinic is a preprocessor for CPython C files.
14+
It was introduced in Python 3.4 with :pep:`436`,
15+
in order to provide introspection signatures,
16+
and to generate performant and tailor-made boilerplate code
17+
for argument parsing in CPython builtins, module level functions, and class methods.
18+
This document is divided in four major sections:
1419

15-
Argument Clinic is a preprocessor for CPython C files.
16-
It was introduced in Python 3.4 with :pep:`436`,
17-
in order to provide introspection signatures,
18-
and to generate performant and tailor-made boilerplate code
19-
for argument parsing in CPython builtins,
20-
module level functions, and class methods.
21-
This document is divided in four major sections:
22-
23-
* :ref:`clinic-background` talks about the basic concepts and goals of
24-
Argument Clinic.
25-
* :ref:`clinic-reference` describes the command-line interface and Argument
26-
Clinic terminology.
27-
* :ref:`clinic-tutorial` guides you through all the steps required to
28-
adapt an existing C function to Argument Clinic.
29-
* :ref:`clinic-howtos` details how to handle specific tasks.
20+
* :ref:`clinic-background` talks about the basic concepts and goals of Argument Clinic.
21+
* :ref:`clinic-reference` describes the command-line interface and Argument Clinic terminology.
22+
* :ref:`clinic-tutorial` guides you through all the steps required to adapt an existing C function to Argument Clinic.
23+
* :ref:`clinic-howtos` details how to handle specific tasks.
3024

3125

3226
.. note::
@@ -749,7 +743,7 @@ While functions using this approach can often be converted to
749743
use :c:func:`!PyArg_ParseTupleAndKeywords`, optional arguments, and default values,
750744
it's not always possible. Some of these legacy functions have
751745
behaviors :c:func:`!PyArg_ParseTupleAndKeywords` doesn't directly support.
752-
The most obvious example is the builtin function :py:func:`range`, which has
746+
The most obvious example is the builtin function :py:func:`!range`, which has
753747
an optional argument on the *left* side of its required argument!
754748
Another example is :py:meth:`curses.window.addch`, which has a group of two
755749
arguments that must always be specified together. (The arguments are
@@ -1358,7 +1352,7 @@ module level state. Use :c:func:`PyType_FromModuleAndSpec` to associate a new
13581352
heap type with a module. You can now use :c:func:`PyType_GetModuleState` on
13591353
the defining class to fetch the module state, for example from a module method.
13601354

1361-
Example from :source:`Modules/zlibmodule.c`.
1355+
Example from :cpy-file:`Modules/zlibmodule.c`.
13621356
First, ``defining_class`` is added to the clinic input::
13631357

13641358
/*[clinic input]
@@ -1399,7 +1393,7 @@ It is not possible to use ``defining_class`` with slot methods. In order to
13991393
fetch the module state from such methods, use :c:func:`PyType_GetModuleByDef`
14001394
to look up the module and then :c:func:`PyModule_GetState` to fetch the module
14011395
state. Example from the ``setattro`` slot method in
1402-
:source:`Modules/_threadmodule.c`::
1396+
:cpy-file:`Modules/_threadmodule.c`::
14031397

14041398
static int
14051399
local_setattro(localobject *self, PyObject *name, PyObject *v)
@@ -1437,7 +1431,7 @@ will be passed along to your :py:meth:`!converter_init` method.
14371431
See :py:class:`CConverter` for a list of members you may wish to specify in
14381432
your subclass.
14391433

1440-
Here's the simplest example of a custom converter, from :source:`Modules/zlibmodule.c`::
1434+
Here's the simplest example of a custom converter, from :cpy-file:`Modules/zlibmodule.c`::
14411435

14421436
/*[python input]
14431437

@@ -1470,7 +1464,7 @@ converters are themselves much simpler.
14701464
Return converters must subclass :py:class:`!CReturnConverter`.
14711465
There are no examples yet of custom return converters,
14721466
because they are not widely used yet. If you wish to
1473-
write your own return converter, please read :source:`Tools/clinic/clinic.py`,
1467+
write your own return converter, please read :cpy-file:`Tools/clinic/clinic.py`,
14741468
specifically the implementation of :py:class:`!CReturnConverter` and
14751469
all its subclasses.
14761470

@@ -1917,7 +1911,7 @@ The ``@text_signature`` directive takes one argument:
19171911
the custom signature as a string.
19181912
The provided signature is copied verbatim to the generated docstring.
19191913

1920-
Example from :source:`Objects/codeobject.c`::
1914+
Example from :cpy-file:`Objects/codeobject.c`::
19211915

19221916
/*[clinic input]
19231917
@text_signature "($self, /, **changes)"

0 commit comments

Comments
 (0)