Add links to hpx header files

cmake/templates/conf.py.in

@@ -78,6 +78,29 @@ def get_info_from_file(source):
 
     return title, header
 
+# Dictionary including the hpx headers with their base path
+# needed to link to the hpx header files themselves.
+# Links generated by docs/sphinx/extensions/sphinx-hpx.py
+# The text in the rst file should be:
+# :hpx-header:`base_path,file_name`
+link_hpx_headers = {
+    "libs/full/include/include": ["hpx/algorithm.hpp", "hpx/barrier.hpp", "hpx/channel.hpp", "hpx/future.hpp", "hpx/latch.hpp", "hpx/runtime.hpp"],
+    "libs/core/include_local/include": ["hpx/any.hpp", "hpx/chrono.hpp", "hpx/condition_variable.hpp", "hpx/exception.hpp", "hpx/execution.hpp", "hpx/functional.hpp", "hpx/mutex.hpp", "hpx/memory.hpp", "hpx/numeric.hpp", "hpx/optional.hpp", "hpx/source_location.hpp", "hpx/system_error.hpp", "hpx/task_block.hpp", "hpx/experimental/task_group.hpp", "hpx/thread.hpp", "hpx/semaphore.hpp", "hpx/shared_mutex.hpp", "hpx/stop_token.hpp", "hpx/tuple.hpp", "hpx/type_traits.hpp", "hpx/unwrap.hpp"],
+    "libs/full/init_runtime/include": ["hpx/init.hpp"],
+    "libs/core/version/include": ["hpx/version.hpp"],
+    "wrap/include": ["hpx/wrap_main.hpp"]
+}
+
+def find_link_hpx_header(include_header):
+
+    for base_path, header_list in link_hpx_headers.items():
+        if include_header in header_list:
+            header_link = f":hpx-header:`{base_path},{include_header}`"
+            break
+        else:
+            header_link = include_header
+    return header_link
+
 # Scan the libs directory for source files to be included in
 # the documentation
 file_regex = re.compile(r'.*\.(h|hxx|hpp|ipp)$')
@@ -176,7 +199,7 @@ api_header_file = '''
 {2}
 -------------------------------------------------------------------------------
 
-Defined in header {3}
+Defined in header {3}.
 
 See :ref:`public_api` for a list of names and headers that are part of the public
 |hpx| API.
@@ -223,7 +246,7 @@ for lib in hpx_libs.keys():
                 include_header = header
 
             header_ref = open(basedir + '/' + header_name + '.rst', 'w')
-            header_ref.write(api_header_file.format(header, module, page_title, include_header))
+            header_ref.write(api_header_file.format(header, module, page_title, find_link_hpx_header(include_header)))
             header_ref.close()
             header_refs += '   /libs/' + lib + '/' + module + '/api/' + header_name + '.rst\n'
         module_api_ref.write(api_file)

docs/sphinx/api/public_api.rst

@@ -1117,7 +1117,7 @@ Classes
 ``hpx/unwrap.hpp``
 ==================
 
-The header :hpx-header:`libs/fcore/include_local/include,hpx/unwrap.hpp` contains utilities for
+The header :hpx-header:`libs/core/include_local/include,hpx/unwrap.hpp` contains utilities for
 unwrapping futures.
 
 Classes

libs/core/synchronization/include/hpx/synchronization/stop_token.hpp

@@ -534,7 +534,7 @@ namespace hpx {
         template <typename CB,
             typename Enable =
                 std::enable_if_t<std::is_constructible_v<Callback, CB>>>
-        explicit stop_callback(stop_token && st, CB && cb) noexcept(
+        explicit stop_callback(stop_token&& st, CB&& cb) noexcept(
             std::is_nothrow_constructible_v<Callback, CB>)
           : callback_(HPX_FORWARD(CB, cb))
           , state_(HPX_MOVE(st.state_))
@@ -559,7 +559,7 @@ namespace hpx {
         }
 
         stop_callback(stop_callback const&) = delete;
-        stop_callback(stop_callback &&) = delete;
+        stop_callback(stop_callback&&) = delete;
 
         stop_callback& operator=(stop_callback const&) = delete;
         stop_callback& operator=(stop_callback&&) = delete;
@@ -945,8 +945,8 @@ namespace hpx::p2300_stop_token {
         template <typename CB,
             typename Enable =
                 std::enable_if_t<std::is_constructible_v<Callback, CB>>>
-        explicit in_place_stop_callback(in_place_stop_token && st,
-            CB && cb) noexcept(std::is_nothrow_constructible_v<Callback, CB>)
+        explicit in_place_stop_callback(in_place_stop_token&& st,
+            CB&& cb) noexcept(std::is_nothrow_constructible_v<Callback, CB>)
           : callback_(HPX_FORWARD(CB, cb))
           , source_(const_cast<in_place_stop_source*>(st.source_))
         {
@@ -979,12 +979,12 @@ namespace hpx::p2300_stop_token {
         }
 
         in_place_stop_callback(in_place_stop_callback const&) = delete;
-        in_place_stop_callback(in_place_stop_callback &&) noexcept = delete;
+        in_place_stop_callback(in_place_stop_callback&&) noexcept = delete;
 
-        in_place_stop_callback& operator=(in_place_stop_callback const&) =
-            delete;
-        in_place_stop_callback& operator=(in_place_stop_callback&&) noexcept =
-            delete;
+        in_place_stop_callback& operator=(
+            in_place_stop_callback const&) = delete;
+        in_place_stop_callback& operator=(
+            in_place_stop_callback&&) noexcept = delete;
 
     private:
         void execute() noexcept override

libs/core/threading_base/include/hpx/threading_base/scoped_annotation.hpp

@@ -44,7 +44,7 @@ namespace hpx {
         explicit constexpr scoped_annotation(char const*) noexcept {}
 
         template <typename F>
-        explicit HPX_HOST_DEVICE constexpr scoped_annotation(F &&) noexcept
+        explicit HPX_HOST_DEVICE constexpr scoped_annotation(F&&) noexcept
         {
         }
 
@@ -85,7 +85,7 @@ namespace hpx {
         template <typename F,
             typename =
                 std::enable_if_t<!std::is_same_v<std::decay_t<F>, std::string>>>
-        explicit scoped_annotation(F && f)
+        explicit scoped_annotation(F&& f)
           : task_(thread_domain_,
                 hpx::traits::get_function_annotation_itt<std::decay_t<F>>::call(
                     f))
@@ -160,7 +160,7 @@ namespace hpx {
         template <typename F,
             typename =
                 std::enable_if_t<!std::is_same_v<std::decay_t<F>, std::string>>>
-        explicit scoped_annotation(F && f)
+        explicit scoped_annotation(F&& f)
         {
             auto const* self = hpx::threads::get_self_ptr();
             if (self != nullptr)
@@ -203,8 +203,7 @@ namespace hpx {
         explicit constexpr scoped_annotation(char const* /*name*/) noexcept {}
 
         template <typename F>
-        explicit HPX_HOST_DEVICE constexpr scoped_annotation(
-            F && /*f*/) noexcept
+        explicit HPX_HOST_DEVICE constexpr scoped_annotation(F&& /*f*/) noexcept
         {
         }