From 62723cfd5f676180cb197a22578f246026d3377d Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 20 Jul 2023 00:40:01 +0200 Subject: [PATCH 1/5] Docs: Add Background and Tutorial top-level sections Add Background as a toplevel section with the following subsections: - Background - The goals of Argument Clinic - Basic concepts and usage Rename "Converting your first function" to: "Tutorial -- converting your first function" Add anchors for Background, Tutorial, and How-to Guides: - :ref:`clinic-background` - :ref:`clinic-tutorial` - :ref:`clinic-howtos` Link to these from within the Abstract. Break the compatibility paragraph out of Abstract and make it a note. --- Doc/howto/clinic.rst | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index efeb22c618b512..d77b56a2820937 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -13,12 +13,19 @@ Argument Clinic How-To Argument Clinic is a preprocessor for CPython C files. Its purpose is to automate all the boilerplate involved - with writing argument parsing code for "builtins". - This document shows you how to convert your first C - function to work with Argument Clinic, and then introduces - some advanced topics on Argument Clinic usage. + with writing argument parsing code for "builtins", + module level functions, and class methods. + This document is divided in three major sections: - Currently Argument Clinic is considered internal-only + * :ref:`clinic-background` talks about the basic concepts and goals of + Argument Clinic. + * :ref:`clinic-tutorial` + * :ref:`clinic-howtos` details how to handle specific tasks. + + +.. note:: + + Argument Clinic is considered internal-only for CPython. Its use is not supported for files outside CPython, and no guarantees are made regarding backwards compatibility for future versions. In other words: if you @@ -28,14 +35,20 @@ Argument Clinic How-To of CPython *could* be totally incompatible and break all your code. +.. _clinic-background: + +Background +========== + + The goals of Argument Clinic -============================ +---------------------------- Argument Clinic's primary goal is to take over responsibility for all argument parsing code inside CPython. This means that, when you convert a function to work with Argument Clinic, that function should no longer -do any of its own argument parsing—the code generated by +do any of its own argument parsing -- the code generated by Argument Clinic should be a "black box" to you, where CPython calls in at the top, and your code gets called at the bottom, with ``PyObject *args`` (and maybe ``PyObject *kwargs``) @@ -80,7 +93,7 @@ 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``. If you run that script, specifying a C file as an argument: @@ -142,8 +155,11 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic: a block.) -Converting your first function -============================== +.. _clinic-tutorial: + + +Tutorial -- converting your first function +========================================== The best way to get a sense of how Argument Clinic works is to convert a function to work with it. Here, then, are the bare @@ -560,6 +576,9 @@ Let's dive in! Congratulations, you've ported your first function to work with Argument Clinic! +.. _clinic-howtos: + + How-to guides ============= From 532dd98914ecac65b4c7ae24e1a322bb12caf37b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 20 Jul 2023 00:47:30 +0200 Subject: [PATCH 2/5] Style --- Doc/howto/clinic.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index d77b56a2820937..874e98fbbb4a08 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -157,7 +157,6 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic: .. _clinic-tutorial: - Tutorial -- converting your first function ========================================== @@ -578,7 +577,6 @@ Let's dive in! .. _clinic-howtos: - How-to guides ============= From de4490759dd4f2cc0049ad8157ee4c5bd30433c2 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 20 Jul 2023 00:48:12 +0200 Subject: [PATCH 3/5] Remove spurious change --- Doc/howto/clinic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 874e98fbbb4a08..74385881b2c553 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -48,7 +48,7 @@ Argument Clinic's primary goal is to take over responsibility for all argument parsing code inside CPython. This means that, when you convert a function to work with Argument Clinic, that function should no longer -do any of its own argument parsing -- the code generated by +do any of its own argument parsing—the code generated by Argument Clinic should be a "black box" to you, where CPython calls in at the top, and your code gets called at the bottom, with ``PyObject *args`` (and maybe ``PyObject *kwargs``) From c90034024558dfc11e05e18e80226fb355c22f92 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 20 Jul 2023 01:14:48 +0200 Subject: [PATCH 4/5] Address review: need three dashes for em-dash Co-authored-by: Ezio Melotti --- Doc/howto/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 74385881b2c553..b8deebb1a13159 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -157,8 +157,8 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic: .. _clinic-tutorial: -Tutorial -- converting your first function -========================================== +Tutorial --- converting your first function +=========================================== The best way to get a sense of how Argument Clinic works is to convert a function to work with it. Here, then, are the bare From c1bf9775905586b927d52502668aa5c03fd4eedc Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 20 Jul 2023 19:43:18 +0200 Subject: [PATCH 5/5] Address review --- Doc/howto/clinic.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index b8deebb1a13159..f6bf1d2234f88d 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -19,7 +19,8 @@ Argument Clinic How-To * :ref:`clinic-background` talks about the basic concepts and goals of Argument Clinic. - * :ref:`clinic-tutorial` + * :ref:`clinic-tutorial` guides you through all the steps required to + adapt an existing C function to Argument Clinic. * :ref:`clinic-howtos` details how to handle specific tasks. @@ -157,8 +158,8 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic: .. _clinic-tutorial: -Tutorial --- converting your first function -=========================================== +Tutorial +======== The best way to get a sense of how Argument Clinic works is to convert a function to work with it. Here, then, are the bare