DOC: Mention more error paths and try to consolidate import errors

The first section was nice, but outdated since NumPy 1.25 effectively
solved the issue so that builds have to be quite old to run into the
previous paths.

OTOH, the NumPy 2 specific section would now overlap if fixing the
first.  So tried to use the first section but expand/rephrase it.

In practice, C-API/Attribute errors, etc. won't be the only reason
for things not working (e.g. the error could just as well be a missing
attribute due to the Python API change), but let's focus on the C API...

My main thought was that mentioning that dtype change error is good,
it is an unfortunate thing that Cython seems to check that before
trying to import NumPy, but it is also a pretty "obvious" error.

Author: seberg

doc/source/user/troubleshooting-importerror.rst

@@ -148,67 +148,75 @@ This may mainly help you if you are not running the python and/or NumPy
 version you are expecting to run.
 
 
-C-API incompatibility
----------------------------
+Downstream ImportError, AttributeError or C-API/ABI incompatibility
+===================================================================
 
-If you see an error like:
+If you see a message such as::
 
+    A module that was compiled using NumPy 1.x cannot be run in
+    NumPy 2.0.0 as it may crash. To support both 1.x and 2.x
+    versions of NumPy, modules must be compiled with NumPy 2.0.
+    Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.
 
-    RuntimeError: module compiled against API version v1 but this version of numpy is v2
+either as an ``ImportError`` or with::
 
+    AttributeError: _ARRAY_API not found
 
-You may have:
+or other errors such as::
 
-* A bad extension "wheel" (binary install) that should use
-  `oldest-support-numpy <https://pypi.org/project/oldest-supported-numpy/>`_ (
-  with manual constraints if necessary) to build their binary packages.
+    RuntimeError: module compiled against API version v1 but this version of numpy is v2
 
-* An environment issue messing with package versions.
+or when a package implemented with Cython::
 
-* Incompatible package versions somehow enforced manually.
+    ValueError: numpy.dtype size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObject
 
-* An extension module compiled locally against a very recent version
-  followed by a NumPy downgrade.
+This means that a package depending on NumPy was build in a way that is not
+compatible with the NumPy version found.
+If this error is due to a recent upgrade to NumPy 2, the easiest solution may
+be to simply downgrade NumPy to ``'numpy<2'``.
 
-* A compiled extension copied to a different computer with an
-  older NumPy version.
+To understand the cause, search the traceback (from the back) to find the first
+line that isn't inside NumPy to see which package has the incompatibility.
+Note your NumPy version and the version of the incompatible package to
+help you find the best solution.
 
-The best thing to do if you see this error is to contact
-the maintainers of the package that is causing problem
-so that they can solve the problem properly.
+There can be various reason for the incompatibility:
 
-However, while you wait for a solution, a work around
-that usually works is to upgrade the NumPy version::
+* You have recently upgraded NumPy, most likely to NumPy 2, and the other
+  module now also needs to be upgraded.  (NumPy 2 was released in June 2024.)
 
+* Especially if you have version constraints on some packages, ``pip`` may
+  have found incompatible versions when installing.
 
-    pip install numpy --upgrade
+* Manual forced versions or setup steps, such as copying a compiled extension
+  to another computer with a different NumPy version.
 
+The best solution will usually be to upgrade the failing package:
 
-Downstream ImportError or AttributeError
-========================================
+* If you installed it for example through ``pip``, try upgrading it with
+  ``pip install package_name --upgrade``.
 
-If you see a message such as::
+* If it is your own package or it is build locally, you need recompiled
+  for the new NumPy version (for details see :ref:`depending_on_numpy`).
+  It may be that a reinstall of the package is sufficient to fix it.
 
-    A module that was compiled using NumPy 1.x cannot be run in
-    NumPy 2.0.0 as it may crash. To support both 1.x and 2.x
-    versions of NumPy, modules must be compiled with NumPy 2.0.
-    Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.
+When these steps fail, you should inform the package maintainers since they
+probably need to make a new, compatible, release.
 
-Either as an ``ImportError`` or with::
+However, upgrading may not always be possible because a compatible version does
+not yet exist or cannot be installed for other reasons.  In that case:
 
-    AttributeError: _ARRAY_API not found
+* Install a compatible NumPy version:
 
-Then you are using NumPy 2 together with a module that was build with NumPy 1.
-NumPy 2 made some changes that require rebuilding such modules to avoid
-possibly incorrect results or crashes.
+  * Try downgrading NumPy with ``pip install 'numpy<2'``
+    (NumPy 2 was released in June 2024).
+  * If your NumPy version is old, you can try upgrading it for
+    example with ``pip install numpy --upgrade``.
 
-As the error message suggests, the easiest solution is likely to downgrade
-NumPy to `numpy<2`.
-Alternatively, you can search the traceback (from the back) to find the first
-line that isn't inside NumPy to see which module needs to be updated.
+* Add additional version pins to the failing package to help ``pip``
+  resolve compatible versions of NumPy and the package.
 
-NumPy 2 was released in the first half of 2024 and especially smaller
-modules downstream are expected need time to adapt and publish a new version.
+* Investigate how the packages got installed and why incompatibilities arose.
 
 
 Segfaults or crashes