[3.11] Docs: Argument Clinic: Group guides about default values (GH-106872) (#106873)

Docs: Argument Clinic: Group guides about default values (GH-106872)

Previous ToC layout (excerpt):

    - How to use symbolic default values
    ...
    - How to assign default values to parameter
      - How to use the ``NULL`` default value
      - How to use expressions as default values

New layout:

    - How to assign default values to parameter
      - The ``NULL`` default value
      - Symbolic default values
      - Expressions as default values

(cherry picked from commit 505eede38d141d43e40e246319b157e3c77211d3)

Co-authored-by: Erlend E. Aasland <erlend@python.org>

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 287a4acebb13309743976814e9eeb95328eecd43..c2e5a68fb9eb21a938689a46c324d4746034a72b 100644 (file)
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -556,22 +556,6 @@ How-to guides
 =============
 
 
-How to use symbolic default values
-----------------------------------
-
-The default value you provide for a parameter can't be any arbitrary
-expression.  Currently the following are explicitly supported:
-
-* Numeric constants (integer and float)
-* String constants
-* ``True``, ``False``, and ``None``
-* Simple symbolic constants like ``sys.maxsize``, which must
-  start with the name of the module
-
-(In the future, this may need to get even more elaborate,
-to allow full expressions like ``CONSTANT - 1``.)
-
-
 How to to rename C functions and variables generated by Argument Clinic
 -----------------------------------------------------------------------
 
@@ -954,8 +938,8 @@ There's also special support for a default value of ``NULL``, and
 for simple expressions, documented in the following sections.
 
 
-How to use the ``NULL`` default value
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The ``NULL`` default value
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For string and object parameters, you can set them to ``None`` to indicate
 that there's no default.  However, that means the C variable will be
@@ -965,8 +949,24 @@ behaves like a default value of ``None``, but the C variable is initialized
 with ``NULL``.
 
 
-How to use expressions as default values
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Symbolic default values
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The default value you provide for a parameter can't be any arbitrary
+expression.  Currently the following are explicitly supported:
+
+* Numeric constants (integer and float)
+* String constants
+* ``True``, ``False``, and ``None``
+* Simple symbolic constants like ``sys.maxsize``, which must
+  start with the name of the module
+
+(In the future, this may need to get even more elaborate,
+to allow full expressions like ``CONSTANT - 1``.)
+
+
+Expressions as default values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The default value for a parameter can be more than just a literal value.
 It can be an entire expression, using math operators and looking up attributes