Merge pull request #2276 from JohanMabille/doc

Slight reorganization fo documentation

Author: JohanMabille

docs/source/build-options.rst

@@ -39,6 +39,8 @@ The following macros are helpers for debugging, they are not defined by default:
 - ``XTENSOR_ENABLE_CHECK_DIMENSION``: enables the dimensions check in ``xtensor``. Note that this option should not be turned
   on if you expect ``operator()`` to perform broadcasting.
 
+.. _external-dependencies:
+
 External dependencies
 ---------------------
 

docs/source/index.rst

@@ -69,8 +69,7 @@ for details.
    missing
    histogram
    random
-   sfinae
-   xsimd
+   rank
    file_loading
    build-options
    pitfall

docs/source/pitfall.rst

@@ -132,3 +132,45 @@ curious compilation error may occur on Windows:
 
 To avoid this compiler bug (for which we don't have a workaround), ensure
 all the elements in the initializer list have the same type.
+
+Alignment of fixed-size members
+-------------------------------
+
+.. note::
+
+    If you are using ``C++ >= 17`` you should not have to worry about this.
+
+When building with ``xsimd`` (see :ref:`external-dependencies`), if you define a structure
+having members of fixed-size xtensor types, you must ensure that the buffers properly
+aligned. For this you can use the macro ``XTENSOR_FIXED_ALIGN`` available in
+``xtensor/xtensor_config.hpp``.
+Consider the following example:
+
+.. code-block:: cpp
+
+    template <typename T>
+    class alignas(XTENSOR_FIXED_ALIGN) Foo
+    {
+    public:
+
+        using allocator_type = std::conditional_t<XTENSOR_FIXED_ALIGN != 0,
+                                                  xt_simd::aligned_allocator<T, XTENSOR_FIXED_ALIGN>,
+                                                  std::allocator<T>>;
+
+        Foo(T fac) : m_fac(fac)
+        {
+            m_bar.fill(fac);
+        }
+
+        auto get() const
+        {
+            return m_bar;
+        }
+
+    private:
+
+        xt::xtensor_fixed<T, xt::xshape<10, 10>> m_bar;
+        T m_fac;
+    };
+
+Whereby it is important to store the fixed-sized xtensor type (in this case ``xt::xtensor_fixed<T, xt::xshape<10, 10>>``) as first member.

docs/source/sfinae.rst docs/source/rank.rstdocs/source/sfinae.rst renamed to docs/source/rank.rst

@@ -4,10 +4,10 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-.. _sfinae:
+.. _rank:
 
-SFINAE
-======
+Tensor Rank
+===========
 
 Rank overload
 -------------