[Python-checkins] [3.11] Docs: Argument Clinic: Add Background and Tutorial top-level sections (GH-106904) (#106946)

[erlend-aasland]

https://github.com/python/cpython/commit/0a57620887f9877398c44062539da3e58235f0e6
commit: 0a57620887f9877398c44062539da3e58235f0e6
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-07-21T08:32:56+02:00
summary:

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

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 81861fd90b4ae981e7881cd03a3c370713063525)

Co-authored-by: Erlend E. Aasland <erlend at python.org>
Co-authored-by: Ezio Melotti <ezio.melotti at gmail.com>

files:
M Doc/howto/clinic.rst

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index c2e5a68fb9eb2..50703d9b4723d 100644
--- 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
@@ -552,6 +568,8 @@ Let's dive in!
     Congratulations, you've ported your first function to work with Argument Clinic!
 
 
+.. _clinic-howtos:
+
 How-to guides
 =============