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