Merge pull request #1304 from msimberg/more-execution-docs

Expand `execution` documentation

docs/api.rst

@@ -74,6 +74,19 @@ The ``pika/init.hpp`` header provides functionality to manage the pika runtime.
 ======================
 
 The ``pika/execution.hpp`` header provides functionality related to ``std::execution``.
+``std::execution`` functionality, including extensions provided by pika, is defined in the
+``pika::execution::experimental`` namespace. When the CMake option ``PIKA_WITH_STDEXEC`` is enabled,
+pika pulls the ``stdexec`` namespace into ``pika::execution::experimental``.
+
+See :ref:`pika_stdexec` and :ref:`std_execution_more_resources` for more details on how pika relates
+to ``std::execution`` and for more resources on learning about ``std::execution``. Documentation for
+sender functionality added to the C++ standard in the above resources apply to both pika's and
+stdexec's implementations of them.
+
+Documented below are sender adaptors not available in stdexec or not proposed for standardization.
+
+All sender adaptors are `customization point objects (CPOs)
+<https://eel.is/c++draft/customization.point.object>`__.
 
 .. doxygenvariable:: pika::execution::experimental::drop_value
 

docs/usage.rst

@@ -312,13 +312,16 @@ More resources
 .. |cppreference_execution| replace:: documentation about ``std::execution``
 .. _cppreference_execution: https://en.cppreference.com/w/cpp/experimental/execution
 
-The `P2300 proposal <https://wg21.link/p2300>`__ is the source of truth for ``std::execution``
-functionality. The reference implementation of P2300, stdexec, maintains a |stdexec_resources|_.  In
-addition to the above, other implementations of the ``std::execution`` model exist, with useful
-documentation and examples:
+The `C++ standard <https://eel.is/c++draft/exec>`__ is the source of truth for ``std::execution``.
+The `P2300 proposal <https://wg21.link/p2300>`__ also contains both the wording for the majority of
+``std::execution`` functionality as well as the motivation for it. The reference implementation of
+P2300, stdexec, maintains a |stdexec_resources|_.  In addition to the above, other implementations
+of the ``std::execution`` model exist, with useful documentation and examples:
 
 - `HPX <https://hpx-docs.stellar-group.org/latest/html/index.html>`__
 - `libunifex <https://github.com/facebookexperimental/libunifex/blob/main/doc/overview.md>`__
+- `C++ Baremetal Senders & Receivers <https://intel.github.io/cpp-baremetal-senders-and-receivers/>`__
+- `execution26 <https://github.com/beman-project/execution26>`__
 
 Even though the implementations differ, the concepts are transferable between implementations and
 useful for learning. cppreference.com also contains early |cppreference_execution|_.