[3.12] Docs: Argument Clinic: Add Background and Tutorial top-level sections (GH-106904) (#106945)

miss-islington · erlend-aasland · ezio-melotti · web-flow · commit 1a3766bb3e5a · 2023-07-21T08:18:18.000+02:00
Docs: Argument Clinic: Add Background and Tutorial top-level sections (GH-106904) 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. 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. (cherry picked from commit 81861fd) Co-authored-by: Erlend E. Aasland <erlend@python.org> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
@@ -13,12 +13,20 @@ 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` 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.
+
+
+.. 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,8 +36,14 @@ 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
@@ -80,7 +94,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 +156,10 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic:
   a block.)
 
 
-Converting your first function
-==============================
+.. _clinic-tutorial:
+
+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
@@ -560,6 +576,8 @@ Let's dive in!
     Congratulations, you've ported your first function to work with Argument Clinic!
 
 
+.. _clinic-howtos:
+
 How-to guides
 =============
 
