Rewrite 'Regenerating configure' section of building guide (#1109)

Author: erlend-aasland

getting-started/setup-building.rst

@@ -477,31 +477,49 @@ Regenerate ``configure``
 
 If a change is made to Python which relies on some POSIX system-specific
 functionality (such as using a new system call), it is necessary to update the
-``configure`` script to test for availability of the functionality.
+:cpy-file:`configure` script to test for availability of the functionality.
+Python's :file:`configure` script is generated from :cpy-file:`configure.ac`
+using `GNU Autoconf <https://www.gnu.org/software/autoconf/>`_.
 
-Python's ``configure`` script is generated from ``configure.ac`` using Autoconf.
-Instead of editing ``configure``, edit ``configure.ac`` and then run
-``autoreconf`` to regenerate ``configure`` and a number of other files (such as
-``pyconfig.h``).
+After editing :file:`configure.ac`, run ``make regen-configure`` to generate
+:file:`configure`, :cpy-file:`pyconfig.h.in`, and :cpy-file:`aclocal.m4`.
+When submitting a pull request with changes made to :file:`configure.ac`,
+make sure you also commit the changes in the generated files.
 
-When submitting a patch with changes made to ``configure.ac``, you should also
-include the generated files.
+The recommended and by far the easiest way to regenerate :file:`configure` is::
 
-Note that running ``autoreconf`` is not the same as running ``autoconf``. For
-example, ``autoconf`` by itself will not regenerate ``pyconfig.h.in``.
-``autoreconf`` runs ``autoconf`` and a number of other tools repeatedly as is
-appropriate.
+   $ make regen-configure
 
-Python's ``configure.ac`` script typically requires a specific version of
-Autoconf.  At the moment, this reads: ``AC_PREREQ(2.69)``. It also requires
-to have the ``autoconf-archive`` and ``pkg-config`` utilities installed in
-the system and the ``pkg.m4`` macro file located in the appropriate ``alocal``
-location. You can easily check if this is correctly configured by running::
+If you are regenerating :file:`configure` in a clean repo,
+run one of the following containers instead::
+
+   $ podman run --rm --pull=always -v $(pwd):/src:Z quay.io/tiran/cpython_autoconf:271
+
+::
+
+   $ docker run --rm --pull=always -v $(pwd):/src quay.io/tiran/cpython_autoconf:271
+
+Notice that the images are tagged with ``271``.
+Python's :file:`configure.ac` script requires a specific version of
+GNU Autoconf.
+For Python 3.12 and newer, GNU Autoconf v2.71 is required.
+For Python 3.11 and earlier, GNU Autoconf v2.69 is required.
+For GNU Autoconf v2.69, change the ``:271`` tag to ``:269``.
+
+If you cannot (or don't want to) use the ``cpython_autoconf`` containers,
+install the :program:`autoconf-archive` and :program:`pkg-config` utilities,
+and make sure the :file:`pkg.m4` macro file located in the appropriate
+:program:`aclocal` location::
 
    $ ls $(aclocal --print-ac-dir) | grep pkg.m4
 
-If the system copy of Autoconf does not match this version, you will need to
-install your own copy of Autoconf.
+.. note::
+
+   Running :program:`autoreconf` is not the same as running :program:`autoconf`.
+   For example, running :program:`autoconf` by itself will not regenerate
+   :file:`pyconfig.h.in`.
+   :program:`autoreconf` runs :program:`autoconf` and a number of other tools
+   repeatedly as appropriate.
 
 .. _build_troubleshooting: