Document the header layout migration and update README examples

README.md

@@ -33,7 +33,7 @@ Julia and R bindings, check out the [xtensor-python](https://github.com/xtensor-
 [xtensor-julia](https://github.com/xtensor-stack/Xtensor.jl) and
 [xtensor-r](https://github.com/xtensor-stack/xtensor-r) projects respectively.
 
-Up to version 0.26.0, `xtensor` requires a C++ compiler supporting C++14.
+Before version 0.26.0, `xtensor` requires a C++ compiler supporting C++14.
 `xtensor` 0.26.x requires a C++ compiler supporting C++17.
 `xtensor` 0.27.x requires a C++ compiler supporting C++20.
 
@@ -119,15 +119,19 @@ in `xtensor`. This can be done by defining the macro `XTENSOR_USE_XSIMD`
 
 ## Usage
 
+Upgrading from xtensor 0.25 or earlier? See the
+[header migration guide](https://xtensor.readthedocs.io/en/latest/installation.html#migrating-from-xtensor-0-25-or-earlier)
+for the include paths introduced in 0.26.
+
 ### Basic usage
 
 **Initialize a 2-D array and compute the sum of one of its rows and a 1-D array.**
 
 ```cpp
 #include <iostream>
-#include "xtensor/xarray.hpp"
-#include "xtensor/xio.hpp"
-#include "xtensor/xview.hpp"
+#include "xtensor/containers/xarray.hpp"
+#include "xtensor/io/xio.hpp"
+#include "xtensor/views/xview.hpp"
 
 xt::xarray<double> arr1
   {{1.0, 2.0, 3.0},
@@ -152,8 +156,8 @@ Outputs:
 
 ```cpp
 #include <iostream>
-#include "xtensor/xarray.hpp"
-#include "xtensor/xio.hpp"
+#include "xtensor/containers/xarray.hpp"
+#include "xtensor/io/xio.hpp"
 
 xt::xarray<int> arr
   {1, 2, 3, 4, 5, 6, 7, 8, 9};
@@ -175,8 +179,8 @@ Outputs:
 
 ```cpp
 #include <iostream>
-#include "xtensor/xarray.hpp"
-#include "xtensor/xio.hpp"
+#include "xtensor/containers/xarray.hpp"
+#include "xtensor/io/xio.hpp"
 
 xt::xarray<double> arr1
   {{1.0, 2.0, 3.0},

docs/source/index.rst

@@ -30,11 +30,9 @@ using Python's `buffer protocol`_. For more details on the NumPy bindings,
 check out the xtensor-python_ project. Language bindings for R and Julia are
 also available.
 
-*xtensor* requires a modern C++ compiler supporting C++14. The following C++
-compilers are supported:
-
-- On Windows platforms, Visual C++ 2015 Update 2, or more recent
-- On Unix platforms, gcc 4.9 or a recent version of Clang
+*xtensor* requires a C++ compiler supporting C++20. See
+:ref:`header-migration` for the requirements of earlier releases and how to
+update include paths when upgrading.
 
 Licensing
 ---------

docs/source/installation.rst

@@ -116,4 +116,83 @@ installation mode you choose, you can add *xtensor* to your project using cmake:
     target_include_directories(your_target PUBLIC ${xtensor_INCLUDE_DIRS})
     target_link_libraries(your_target PUBLIC xtensor)
 
+.. _header-migration:
+
+Migrating from xtensor 0.25 or earlier
+--------------------------------------
+
+Starting with xtensor 0.26, headers are organized into subdirectories by
+functionality. Includes such as ``#include <xtensor/xarray.hpp>`` must be
+updated to ``#include <xtensor/containers/xarray.hpp>``. The same change applies
+to includes written with double quotes.
+
+Common replacements are:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 45 55
+
+   * - Before 0.26
+     - Since 0.26
+   * - ``xtensor/xarray.hpp``
+     - ``xtensor/containers/xarray.hpp``
+   * - ``xtensor/xtensor.hpp``
+     - ``xtensor/containers/xtensor.hpp``
+   * - ``xtensor/xfixed.hpp``
+     - ``xtensor/containers/xfixed.hpp``
+   * - ``xtensor/xadapt.hpp``
+     - ``xtensor/containers/xadapt.hpp``
+   * - ``xtensor/xmath.hpp``
+     - ``xtensor/core/xmath.hpp``
+   * - ``xtensor/xeval.hpp``
+     - ``xtensor/core/xeval.hpp``
+   * - ``xtensor/xview.hpp``
+     - ``xtensor/views/xview.hpp``
+   * - ``xtensor/xstrided_view.hpp``
+     - ``xtensor/views/xstrided_view.hpp``
+   * - ``xtensor/xbuilder.hpp``
+     - ``xtensor/generators/xbuilder.hpp``
+   * - ``xtensor/xrandom.hpp``
+     - ``xtensor/generators/xrandom.hpp``
+   * - ``xtensor/xio.hpp``
+     - ``xtensor/io/xio.hpp``
+   * - ``xtensor/xnpy.hpp``
+     - ``xtensor/io/xnpy.hpp``
+   * - ``xtensor/xmanipulation.hpp``
+     - ``xtensor/misc/xmanipulation.hpp``
+   * - ``xtensor/xsort.hpp``
+     - ``xtensor/misc/xsort.hpp``
+   * - ``xtensor/xreducer.hpp``
+     - ``xtensor/reducers/xreducer.hpp``
+   * - ``xtensor/xnorm.hpp``
+     - ``xtensor/reducers/xnorm.hpp``
+
+For other headers, locate the filename under the installed ``include/xtensor``
+directory and use its path relative to ``include``. Update includes in your
+own headers as well as source files. Keep the compiler's include search path
+pointing to the parent of ``xtensor`` (typically ``<prefix>/include``); adding
+each new subdirectory to the search path does not replace updating the
+``#include`` directives. The CMake integration above supplies the include path.
+
+Also check the language standard and xtl dependency when upgrading:
+
+.. list-table::
+   :header-rows: 1
+
+   * - xtensor release
+     - C++ standard
+     - Minimum xtl version
+   * - 0.25.0
+     - C++14
+     - 0.7.5
+   * - 0.26.0
+     - C++17
+     - 0.8.0
+   * - 0.27.0
+     - C++20
+     - 0.8.0
+
+This addresses the header layout change; consult the :doc:`changelog` for other
+API and dependency changes in the release you are upgrading to.
+
 .. _xtl: https://github.com/xtensor-stack/xtl