core(graph): adding documentation for Kokkos::Experimental::Graph

docs/source/API/core-index.rst

@@ -37,6 +37,8 @@ API: Core
      - Utility functionality part of Kokkos Core.
    * - `Detection Idiom <core/Detection-Idiom.html>`__
      - Used to recognize, in an SFINAE-friendly way, the validity of any C++ expression.
+   * - `Graph and related <core/Graph.html>`_
+     - Kokkos Graph abstraction.
    * - `Macros <core/Macros.html>`__
      - Global macros defined by Kokkos, used for architectures, general settings, etc.
 
@@ -60,4 +62,5 @@ API: Core
    ./core/Utilities
    ./core/Detection-Idiom
    ./core/Macros
+   ./core/Graph
    ./core/Profiling

docs/source/API/core/Graph.rst

@@ -0,0 +1,46 @@
+Graph and related
+=================
+
+Usage
+-----
+
+:code:`Kokkos::Graph` is an abstraction that can be used to define a group of asynchronous workloads that are organised as a direct acyclic graph.
+
+:code:`Kokkos::Graph` is a powerful way of describing workload dependencies.
+
+For small workloads that need to be sumitted several times, it might save you some overhead [reference to some presentation / paper].
+
+:code:`Kokkos::Graph` is specialized for some backends:
+
+* :code:`Cuda`: [ref to vendor doc]
+* :code:`HIP`: [ref to vendor doc]
+* :code:`SYCL`: [ref to vendor doc]
+
+For other backends, Kokkos provides a defaulted implementation [ref to file].
+
+Basic example
+-------------
+
+This example showcases how three workloads can be organised as a :code:`Kokkos::Graph`.
+
+Workloads A and B are independent, but workload C needs the completion of A and B.
+
+.. code-block:: cpp
+
+    int main()
+    {
+        auto graph = Kokkos::Experimental::create_graph<Exec>([&](auto root) {
+            const auto node_A = root.then_parallel_for(...label..., ...policy..., ...body...);
+            const auto node_B = root.then_parallel_for(...label..., ...policy..., ...body...);
+            const auto ready  = Kokkos::Experimental::when_all(node_A, node_B);
+            const auto node_C = ready.then_parallel_for(...label..., ...policy..., ...body...);
+        });
+
+        for(int irep = 0; irep < nrep; ++irep)
+            graph.submit();
+    }
+
+Advanced example
+----------------
+
+To be done soon.