[Python-checkins] [3.12] Docs: Argument Clinic: Group guides about default values (GH-106872) (#106874)

[erlend-aasland]

https://github.com/python/cpython/commit/0c106a91e8e54bbf114cb54540dddb2a39a0e2be
commit: 0c106a91e8e54bbf114cb54540dddb2a39a0e2be
branch: 3.12
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-07-19T01:16:19+02:00
summary:

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

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 at python.org>

files:
M Doc/howto/clinic.rst

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 12d7a77d43209..efeb22c618b51 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -564,22 +564,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
 -----------------------------------------------------------------------
 
@@ -965,8 +949,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
@@ -976,8 +960,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