Document header dependencies for source distributions

doc/source/cdef.rst

@@ -353,7 +353,7 @@ code.
 
 The keywords arguments to ``set_source()`` control how the C compiler
 will be called.  They are passed directly to distutils_ or setuptools_
-and include at least ``sources``, ``include_dirs``, ``define_macros``,
+and include at least ``sources``, ``depends``, ``include_dirs``, ``define_macros``,
 ``undef_macros``, ``libraries``, ``library_dirs``, ``extra_objects``,
 ``extra_compile_args`` and ``extra_link_args``.  You typically need at
 least ``libraries=['foo']`` in order to link with ``libfoo.so`` or
@@ -367,6 +367,17 @@ first argument to ``sources``).  See the distutils documentation for
 .. _distutils: http://docs.python.org/3.11/distutils/setupscript.html#describing-extension-modules
 .. _setuptools: https://setuptools.pypa.io/
 
+If your C sources include project-local header files, list those files in
+``depends``, for example ``depends=['pi.h']``.  Setuptools uses this list
+both to detect when an extension needs rebuilding and to include the files
+in a source distribution.  Use paths relative to the project root.
+``include_dirs`` only tells the compiler where to search for headers; it
+does not add those headers to the source distribution.  Without them, a
+wheel built from the source distribution (as done by ``python -m build``)
+can fail even if compilation from the working tree succeeds.  List the
+headers themselves, including any project-local headers they include;
+``depends`` does not recursively discover ``#include`` dependencies.
+
 An extra keyword argument processed internally is
 ``source_extension``, defaulting to ``".c"``.  The file generated will
 be actually called ``module_name + source_extension``.  Example for

doc/source/overview.rst

@@ -343,6 +343,8 @@ the C extension:
           #include "pi.h"
       """,
           sources=['pi.c'],   # includes pi.c as additional sources
+          depends=['pi.h'],   # includes pi.h in source distributions
+          include_dirs=['.'], # lets the compiler find pi.h
           libraries=['m'])    # on Unix, link with the math library
 
       if __name__ == "__main__":