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.
python · erlend-aasland · Jul 21, 2023 · Jul 19, 2023 · Jul 19, 2023 · Jul 19, 2023
commit 62723cfd5f676180cb197a22578f246026d3377d
@@ -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
 =============