Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add missing markup to Argument Clinic docs #106876

Merged
merged 22 commits into from
Jul 24, 2023
Merged
Changes from 6 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
e8068e0
Docs: Add missing markup to Argument Clinic docs
erlend-aasland Jul 18, 2023
cf66105
Add missing colon
erlend-aasland Jul 18, 2023
cd940e2
Pull in main
erlend-aasland Jul 19, 2023
6e5c44f
Address reviews
erlend-aasland Jul 19, 2023
d1627ae
Pull in main
erlend-aasland Jul 19, 2023
8f23956
Use :data: for METH_O and METH_NOARGS
erlend-aasland Jul 19, 2023
b155e38
For now, disable the METH_METHOD link
erlend-aasland Jul 19, 2023
971c058
Suggest 'make clinic' and 'make regen-global-objects' iso. running cl…
erlend-aasland Jul 19, 2023
bc33f97
Markup file suffixes and file paths with :file:
erlend-aasland Jul 19, 2023
f5bb4a3
Address review: rewrite line 919 similar to suggestion by Serhiy
erlend-aasland Jul 19, 2023
f892322
fixup! Suggest 'make clinic' and 'make regen-global-objects' iso. run…
erlend-aasland Jul 19, 2023
d96fdeb
Address review: markup more params with **
erlend-aasland Jul 19, 2023
f593853
Pull in main
erlend-aasland Jul 20, 2023
47061df
Address review: revert :program: markups
erlend-aasland Jul 20, 2023
ec6fc6c
Pull in main
erlend-aasland Jul 21, 2023
fe52717
Address review: fix 'int' markup around line 1330
erlend-aasland Jul 21, 2023
1a30f3b
Address review: use new and correct directives for C constants/macros
erlend-aasland Jul 21, 2023
8c69e70
Pull in main
erlend-aasland Jul 22, 2023
499ed66
Revert module.class markup
erlend-aasland Jul 22, 2023
d2f968a
Revert 'make clinic' changes
erlend-aasland Jul 22, 2023
eaaeb42
Pull in main
erlend-aasland Jul 24, 2023
8454b78
METH_METHOD now has its own anchor
erlend-aasland Jul 24, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 13 additions & 14 deletions Doc/howto/clinic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -410,9 +410,8 @@ Let's dive in!
Write a pickled representation of obj to the open file.
[clinic start generated code]*/

12. Save and close the file, then run ``make clinic``
to regenerate the Argument Clinic code.
With luck everything worked---your block now has output, and
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 :file:`.c.h` file has been generated! Reopen the file in your
text editor to see::

Expand Down Expand Up @@ -476,7 +475,7 @@ Let's dive in!

If any of these items differ in *any way*,
adjust your Argument Clinic function specification and rerun
``make clinic`` until they *are* the same.
``Tools/clinic/clinic.py`` until they *are* the same.


14. Notice that the last line of its output is the declaration
Expand Down Expand Up @@ -902,7 +901,7 @@ negative numbers. You just can't do that with a legacy converter!
Argument Clinic will show you all the converters it has
available. For each converter it'll show you all the parameters
it accepts, along with the default value for each parameter.
Just run ``./Tools/clinic/clinic.py --converters`` to see the full list.
Just run ``Tools/clinic/clinic.py --converters`` to see the full list.


How to use the ``Py_buffer`` converter
Expand Down Expand Up @@ -1121,7 +1120,7 @@ For all of these, return ``-1`` to indicate error.

To see all the return converters Argument Clinic supports, along with
their parameters (if any),
just run ``./Tools/clinic/clinic.py --converters`` for the full list.
just run ``Tools/clinic/clinic.py --converters`` for the full list.


How to clone existing functions
Expand Down Expand Up @@ -1158,7 +1157,7 @@ Here's the syntax for cloning a function::
[clinic start generated code]*/

(The functions can be in different modules or classes. I wrote
:py:class:`!module.class` in the sample just to illustrate that you must
``module.class`` in the sample just to illustrate that you must
use the full path to *both* functions.)

Sorry, there's no syntax for partially cloning a function, or cloning a function
Expand Down Expand Up @@ -1290,9 +1289,9 @@ after ``self``, or, if ``self`` is not used, as the first argument. The argumen
will be of type ``PyTypeObject *``. The argument will not appear in the
:py:attr:`!__text_signature__`.

The ``defining_class`` converter is not compatible with
:py:meth:`!__init__` and :py:meth:`!__new__`
methods, which cannot use the :data:`!METH_METHOD` convention.
The ``defining_class`` converter is not compatible with :py:meth:`!__init__`
and :py:meth:`!__new__` methods, which cannot use the :ref:`METH_METHOD
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved
<METH_METHOD-METH_FASTCALL-METH_KEYWORDS>` 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`
Expand Down Expand Up @@ -1345,7 +1344,7 @@ to specify in your subclass. Here's the current list:

The C type to use for this variable.
:attr:`!type` should be a Python string specifying the type,
e.g. :class:`int`.
e.g. ``'int'``.
If this is a pointer type, the type string should end with ``' *'``.

.. attribute:: default
Expand Down Expand Up @@ -1435,7 +1434,7 @@ all its subclasses.
How to convert ``METH_O`` and ``METH_NOARGS`` functions
-------------------------------------------------------

To convert a function using :data:`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::

Expand All @@ -1447,11 +1446,11 @@ arguments as positional-only::
[clinic start generated code]*/


To convert a function using :data:`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 :data:`METH_O`.
a *type* argument to the object converter for :c:macro:`METH_O`.


How to convert ``tp_new`` and ``tp_init`` functions
Expand Down
Loading