Fix miscellaneous issues in the 'Configure Python' docs (#158679)

Author: StanFromIreland

Doc/tools/extensions/pyspecific.py

@@ -11,6 +11,7 @@
 
 import re
 
+from docutils import nodes
 from sphinx import addnodes
 from sphinx.domains.python import PyFunction, PyMethod
 
@@ -78,6 +79,13 @@ def parse_pdb_command(env, sig, signode):
     return fullname
 
 
+def parse_make_target(env, sig, signode):
+    """Transform a make target signature into RST nodes."""
+    signode += addnodes.desc_name(sig, sig)
+    signode['ids'].append(nodes.make_id(sig))
+    return sig
+
+
 def parse_monitoring_event(env, sig, signode):
     """Transform a monitoring event signature into RST nodes."""
     signode += addnodes.desc_addname('sys.monitoring.events.', 'sys.monitoring.events.')
@@ -113,6 +121,7 @@ def setup(app):
     app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
     app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command)
     app.add_object_type('monitoring-event', 'monitoring-event', '%s (monitoring event)', parse_monitoring_event)
+    app.add_object_type('make-target', 'make-target', '%s (make target)', parse_make_target)
     app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
     app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
     app.connect('env-check-consistency', patch_pairindextypes)

Doc/using/configure.rst

@@ -7,7 +7,7 @@ Configure Python
 
 .. _build-requirements:
 
-Build Requirements
+Build requirements
 ==================
 
 To build CPython, you will need:
@@ -171,6 +171,8 @@ platform-specific modules like :mod:`winreg` are not listed here.
    SQLite 3.15.2 is now required for :mod:`sqlite3`.
 
 
+.. _generated-files:
+
 Generated files
 ===============
 
@@ -181,9 +183,11 @@ files. Commands to regenerate all generated files::
     make regen-stdlib-module-names
     make regen-limited-abi
     make regen-configure
+    make regen-sbom
+    make regen-unicodedata
 
-The ``Makefile.pre.in`` file documents generated files, their inputs, and tools used
-to regenerate them. Search for ``regen-*`` make targets.
+The :source:`Makefile.pre.in` file documents generated files, their inputs, and
+tools used to regenerate them. Search for ``regen-*`` make targets.
 
 configure script
 ----------------
@@ -214,7 +218,7 @@ and `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ 1.8.1.
 
 .. _configure-options:
 
-Configure Options
+Configure options
 =================
 
 List all :file:`configure` script options using::
@@ -223,7 +227,7 @@ List all :file:`configure` script options using::
 
 See also the :file:`Misc/SpecialBuilds.txt` in the Python source distribution.
 
-General Options
+General options
 ---------------
 
 .. option:: --enable-loadable-sqlite-extensions
@@ -628,7 +632,7 @@ Options for third-party dependencies
    overriding ``pkg-config``.
 
 
-WebAssembly Options
+WebAssembly options
 -------------------
 
 .. option:: --enable-wasm-dynamic-linking
@@ -647,7 +651,7 @@ WebAssembly Options
    .. versionadded:: 3.11
 
 
-Install Options
+Install options
 ---------------
 
 .. option:: --prefix=PREFIX
@@ -934,7 +938,7 @@ also be used to improve performance.
 
 .. _debug-build:
 
-Python Debug Build
+Python debug build
 ------------------
 
 A debug build is Python built with the :option:`--with-pydebug` configure
@@ -1248,7 +1252,7 @@ Libraries options
    .. versionadded:: 3.10
 
 
-Security Options
+Security options
 ----------------
 
 .. option:: --with-hash-algorithm=[fnv|siphash13|siphash24]
@@ -1326,7 +1330,7 @@ Security Options
    .. versionadded:: 3.14
 
 
-macOS Options
+macOS options
 -------------
 
 See :source:`Mac/README.rst`.
@@ -1381,7 +1385,7 @@ See :source:`Mac/README.rst`.
 
    .. versionadded:: 3.13
 
-iOS Options
+iOS options
 -----------
 
 See :source:`Platforms/Apple/iOS/README.md`.
@@ -1406,7 +1410,7 @@ rejects :option:`--enable-shared`. See
    iOS builds may be configured without a framework.
 
 
-Cross Compiling Options
+Cross compiling options
 -----------------------
 
 Cross compiling, also known as cross building, can be used to build Python
@@ -1456,7 +1460,7 @@ Cross compiling example::
        --with-build-python=../x86_64/python
 
 
-Python Build System
+Python build system
 ===================
 
 Main files of the build system
@@ -1480,107 +1484,88 @@ Main build steps
 Main Makefile targets
 ---------------------
 
-make
-^^^^
-
-For the most part, when rebuilding after editing some code or
-refreshing your checkout from upstream, all you need to do is execute
-``make``, which (per Make's semantics) builds the default target, the
-first one defined in the Makefile.  By tradition (including in the
-CPython project) this is usually the ``all`` target. The
-``configure`` script expands an ``autoconf`` variable,
-``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make
-all`` will build. The three choices are:
-
-* ``profile-opt`` (configured with ``--enable-optimizations``)
-* ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*`` or
-  ``wasm32-emscripten``)
-* ``build_all`` (configured without explicitly using either of the others)
-
-Depending on the most recent source file changes, Make will rebuild
-any targets (object files and executables) deemed out-of-date,
-including running ``configure`` again if necessary. Source/target
-dependencies are many and maintained manually however, so Make
-sometimes doesn't have all the information necessary to correctly
-detect all targets which need to be rebuilt.  Depending on which
-targets aren't rebuilt, you might experience a number of problems. If
-you have build or test problems which you can't otherwise explain,
-``make clean && make`` should work around most dependency problems, at
-the expense of longer build times.
-
-
-make platform
-^^^^^^^^^^^^^
+.. make-target:: make
 
-Build the ``python`` program, but don't build the standard library
-extension modules. This generates a file named ``platform`` which
-contains a single line describing the details of the build platform,
-e.g., ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``.
+   For the most part, when rebuilding after editing some code or
+   refreshing your checkout from upstream, all you need to do is execute
+   ``make``, which (per Make's semantics) builds the default target, the
+   first one defined in the Makefile.  By tradition (including in the
+   CPython project) this is usually the ``all`` target. The
+   ``configure`` script expands an ``autoconf`` variable,
+   ``@DEF_MAKE_ALL_RULE@`` to describe precisely which targets ``make
+   all`` will build. The choices are:
 
+   * ``profile-opt`` (configured with ``--enable-optimizations``)
+   * ``bolt-opt`` (configured with ``--enable-bolt``)
+   * ``build_emscripten`` (chosen if the host platform matches
+     ``wasm32-emscripten``)
+   * ``build_wasm`` (chosen if the host platform matches ``wasm32-wasi*``)
+   * ``build_all`` (configured without explicitly using any of the others)
 
-make profile-opt
-^^^^^^^^^^^^^^^^
+   Depending on the most recent source file changes, Make will rebuild
+   any targets (object files and executables) deemed out-of-date,
+   including running ``configure`` again if necessary. Source/target
+   dependencies are many and maintained manually however, so Make
+   sometimes doesn't have all the information necessary to correctly
+   detect all targets which need to be rebuilt.  Depending on which
+   targets aren't rebuilt, you might experience a number of problems. If
+   you have build or test problems which you can't otherwise explain,
+   ``make clean && make`` should work around most dependency problems, at
+   the expense of longer build times.
 
-Build Python using profile-guided optimization (PGO).  You can use the
-configure :option:`--enable-optimizations` option to make this the
-default target of the ``make`` command (``make all`` or just
-``make``).
+.. make-target:: make platform
 
+   Build the ``python`` program, but don't build the standard library
+   extension modules. This generates a file named ``platform`` which
+   contains a single line describing the details of the build platform,
+   for example, ``macosx-14.3-arm64-3.12`` or ``linux-x86_64-3.13``.
 
+.. make-target:: make profile-opt
 
-make clean
-^^^^^^^^^^
+   Build Python using profile-guided optimization (PGO).  You can use the
+   configure :option:`--enable-optimizations` option to make this the
+   default target of the ``make`` command (``make all`` or just
+   ``make``).
 
-Remove built files.
+.. make-target:: make clean
 
+   Remove built files.
 
-make distclean
-^^^^^^^^^^^^^^
+.. make-target:: make distclean
 
-In addition to the work done by ``make clean``, remove files
-created by the configure script.  ``configure`` will have to be run
-before building again. [#]_
+   In addition to the work done by ``make clean``, remove files
+   created by the configure script.  ``configure`` will have to be run
+   before building again. [#]_
 
+.. make-target:: make install
 
-make install
-^^^^^^^^^^^^
+   Build the ``all`` target and install Python.
 
-Build the ``all`` target and install Python.
+.. make-target:: make test
 
+   Build the ``all`` target and run the Python test suite with the
+   ``--fast-ci`` option without GUI tests. Variables:
 
-make test
-^^^^^^^^^
+   * ``TESTOPTS``: additional regrtest command-line options.
+   * ``TESTPYTHONOPTS``: additional Python command-line options.
+   * ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes).
 
-Build the ``all`` target and run the Python test suite with the
-``--fast-ci`` option without GUI tests. Variables:
+.. make-target:: make ci
 
-* ``TESTOPTS``: additional regrtest command-line options.
-* ``TESTPYTHONOPTS``: additional Python command-line options.
-* ``TESTTIMEOUT``: timeout in seconds (default: 10 minutes).
+   This is similar to ``make test``, but uses the ``-ugui`` to also run GUI tests.
 
+   .. versionadded:: 3.14
 
-make ci
-^^^^^^^
-
-This is similar to ``make test``, but uses the ``-ugui`` to also run GUI tests.
-
-.. versionadded:: 3.14
-
-
-make buildbottest
-^^^^^^^^^^^^^^^^^
-
-This is similar to ``make test``, but uses the ``--slow-ci``
-option and default timeout of 20 minutes, instead of ``--fast-ci`` option.
+.. make-target:: make buildbottest
 
+   This is similar to ``make test``, but uses the ``--slow-ci``
+   option and default timeout of 20 minutes, instead of ``--fast-ci`` option.
 
-make regen-all
-^^^^^^^^^^^^^^
+.. make-target:: make regen-all
 
-Regenerate (almost) all generated files. These include (but are not
-limited to) bytecode cases, and parser generator file.
-``make regen-stdlib-module-names`` and ``autoconf`` must be run
-separately for the remaining `generated files <#generated-files>`_.
+   Regenerate (almost) all generated files. These include (but are not
+   limited to) bytecode cases, and parser generator files. See
+   :ref:`generated-files` for the targets that must be run separately.
 
 
 C extensions
@@ -1600,23 +1585,23 @@ Built-in modules have no ``__file__`` attribute:
       File "<stdin>", line 1, in <module>
     AttributeError: module 'sys' has no attribute '__file__'
 
-Other C extensions are built as dynamic libraries, like the ``_asyncio`` module.
+Other C extensions are built as dynamic libraries, like the ``_zoneinfo`` module.
 They are built with the ``Py_BUILD_CORE_MODULE`` macro defined.
-Example on Linux x86-64:
+For example on Linux x86-64:
 
 .. code-block:: pycon
 
-    >>> import _asyncio
-    >>> _asyncio
-    <module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'>
-    >>> _asyncio.__file__
-    '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'
+    >>> import _zoneinfo
+    >>> _zoneinfo
+    <module '_zoneinfo' from '/.../lib.linux-x86_64-3.16/_zoneinfo.cpython-316d-x86_64-linux-gnu.so'>
+    >>> _zoneinfo.__file__
+    '/.../lib.linux-x86_64-3.16/_zoneinfo.cpython-316d-x86_64-linux-gnu.so'
 
 :file:`Modules/Setup` is used to generate Makefile targets to build C extensions.
 At the beginning of the files, C extensions are built as built-in modules.
 Extensions defined after the ``*shared*`` marker are built as dynamic libraries.
 
-The :c:macro:`!PyAPI_FUNC()`, :c:macro:`!PyAPI_DATA()` and
+The :c:macro:`PyAPI_FUNC()`, :c:macro:`PyAPI_DATA()` and
 :c:macro:`PyMODINIT_FUNC` macros of :file:`Include/exports.h` are defined
 differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined:
 

Makefile.pre.in

@@ -1915,6 +1915,7 @@ regen-unicodedata:
 # Regenerate all generated files
 
 # "clinic" is regenerated implicitly via "regen-global-objects".
+# Keep the list of targets to run manually in sync with Doc/using/configure.rst.
 .PHONY: regen-all
 regen-all: regen-cases regen-slots \
 	regen-token regen-ast regen-keyword regen-sre regen-frozen \