DOC: Skip API documentation for numpy.distutils with Python 3.12 and later

[roehling]

Starting with Python 3.12, the lack of a distutils module makes the documentation build fail with

WARNING: Failed to import numpy.distutils.misc_util.
Possible hints:
* AttributeError: module 'numpy' has no attribute 'distutils'
* ModuleNotFoundError: No module named 'numpy.distutils'

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autosummary/generate.py",
line 503, in generate_autosummary_docs
    name, obj, parent, modname = import_by_name(entry.name)
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/ext/autosummary/__init__.py",
line 655, in import_by_name
    raise ImportExceptionGroup('no module named %s' % ' or
'.join(tried), exceptions)
sphinx.ext.autosummary.ImportExceptionGroup: no module named
numpy.distutils.ccompiler

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/events.py", line 97, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/ext/autosummary/__init__.py",
line 814, in process_generate_options
    generate_autosummary_docs(genfiles, suffix=suffix, base_path=app.srcdir,
  File "/usr/lib/python3/dist-packages/sphinx/ext/autosummary/generate.py",
line 508, in generate_autosummary_docs
    name, obj, parent, modname = import_ivar_by_name(entry.name)
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/ext/autosummary/__init__.py",
line 712, in import_ivar_by_name
    real_name, obj, parent, modname = import_by_name(name, prefixes)
                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/ext/autosummary/__init__.py",
line 655, in import_by_name
    raise ImportExceptionGroup('no module named %s' % ' or
'.join(tried), exceptions)
sphinx.ext.autosummary.ImportExceptionGroup: no module named numpy.distutils

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/cmd/build.py", line 293,
in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/sphinx/application.py", line
271, in __init__
    self._init_builder()
  File "/usr/lib/python3/dist-packages/sphinx/application.py", line
342, in _init_builder
    self.events.emit('builder-inited')
  File "/usr/lib/python3/dist-packages/sphinx/events.py", line 108, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function
process_generate_options at 0x7f03020f05e0> for event 'builder-inited'
threw an exception (exception: no module named numpy.distutils)

Extension error (sphinx.ext.autosummary):

This PR excludes the offending source file from the Sphinx build if built with Python 3.12 or later.

[charris]

This is needed when documentation is built with Python >= 3.12?

[roehling]

This is the way I fixed the Debian build for when Python 3.12 will become the new default Python version (cf. Debian bug 1071255). I am open to alternative suggestions if you know a better/more elegant way to solve the issue.

[charris]

Thanks @roehling .