multiple files extension documentation improved

Author: JohanMabille

docs/source/numpy_capi.rst

@@ -23,7 +23,6 @@ Thus the basic skeleton of the module looks like:
 
 .. code::
 
-    #include "pybind11/pybind11.h"
     #define FORCE_IMPORT_ARRAY
     #include "xtensor-python/pyarray.hpp"
 
@@ -37,9 +36,45 @@ Thus the basic skeleton of the module looks like:
 Extension module with multiple files
 ------------------------------------
 
-If the extension module contain many source files that include ``xtensor-python`` header files, the previous points are still
-required. However, the source files that don't contain the initializing code of the module can directly include ``xtensor-python``
-header files.
+If the extension module contains many source files that include ``xtensor-python`` header files, the previous points are still
+required. However, the symbol ``FORCE_IMPORT_ARRAY`` must be defined only once. The simplest is to define it int the file that
+contains the initializing code of the module, you can then directly include ``xtensor-python`` headers in other files. Let's
+illustrate this with an extension modules containing the following files:
+
+- ``main.cpp``: initializing code of the module
+- ``image.hpp``: declaration of the ``image`` class embedding an ``xt::pyarray`` object
+- ``image.cpp``: implementation of the ``image`` class
+
+The basic skeleton of the module looks like:
+
+.. code::
+
+    // image.hpp
+    // Do NOT define FORCE_IMPORT_ARRAY here
+    #include "xtensor-python/pyarray.hpp"
+
+    class image
+    {
+    // ....
+    private:
+        xt::pyarray<double> m_data;
+    };
+
+    // image.cpp
+    // Do NOT define FORCE_IMPORT_ARRAY here
+    #include "image.hpp"
+    // definition of the image class
+
+    // main.cpp
+    // FORCE_IMPORT_ARRAY must be define ONCE, BEFORE including
+    // any header from xtensor-python (even indirectly)
+    #define FORCE_IMPORT_ARRAY
+    #include "image.hpp"
+    PYBIND11_MODULE(plugin_name, m)
+    {
+        xt::import_numpy();
+        //...
+    }
 
 
 Using other extension modules