Created a new crosslink file to store versioned links. (#1828)

* Created a new crosslink file to store versioned links. Signed-off-by: Benito, Dylan <[email protected]> * Delete the duplicate cross-link file * Rename substitutions. Split long lines. * Improve wording referring to the DPC++ CMake support page --------- Signed-off-by: Benito, Dylan <[email protected]> Co-authored-by: Alexey Kukanov <[email protected]>
uxlfoundation · Nov 15, 2024 · 7fdb5e5 · 7fdb5e5
1 parent 296492b
commit 7fdb5e5
Show file tree

Hide file tree

Showing 8 changed files with 71 additions and 35 deletions.
diff --git a/documentation/library_guide/cmake_support.rst b/documentation/library_guide/cmake_support.rst
@@ -17,7 +17,10 @@ Requirements
 ============
 The minimal supported CMake version for |onedpl_short| is 3.11 on Linux and 3.20 on Windows.
 
-The supported `CMake Generator <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#ninja-generators>`_ for Linux is `Unix Makefiles <https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html>`_ (default). In the Windows environment, the supported generator is `Ninja <https://cmake.org/cmake/help/latest/generator/Ninja.html>`_ as described in the `Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/current/use-cmake-with-the-compiler.html>`_ which may be specified via ``-GNinja``.
+The supported `CMake Generator <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#ninja-generators>`_
+for Linux is `Unix Makefiles <https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html>`_ (default).
+In the Windows environment, the supported generator is `Ninja <https://cmake.org/cmake/help/latest/generator/Ninja.html>`_
+which may be specified via ``-GNinja`` as described in the |dpcpp_cmake_support|_.
 
 |onedpl_short| Backend Options
 ==============================

diff --git a/documentation/library_guide/common_cross_document_links.txt b/documentation/library_guide/common_cross_document_links.txt
@@ -0,0 +1,26 @@
+.. |onedpl_library_guide| replace:: Intel® oneAPI DPC++ Library Guide
+.. _onedpl_library_guide: https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/2022-7/overview.html
+
+.. |dpcpp_gsg| replace:: Get Started with the Intel® oneAPI DPC++/C++ Compiler
+.. _dpcpp_gsg: https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/get-started-guide/2024-2/overview.html
+
+.. |dpcpp_cpp_with_gsg_link| replace:: Intel® oneAPI DPC++/C++ Compiler
+.. _dpcpp_cpp_with_gsg_link: https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/get-started-guide/2024-2/overview.html
+
+.. |dpcpp_cmake_support| replace:: CMake support documentation for the Intel® oneAPI DPC++/C++ Compiler
+.. _dpcpp_cmake_support: https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2024-2/use-cmake-with-the-compiler.html
+
+.. |vector_pragma| replace:: pragma vector documentation in the Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference
+.. _vector_pragma: https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2024-2/vector.html
+
+.. |unroll_pragma| replace:: unroll Pragma
+.. _unroll_pragma: https://www.intel.com/content/www/us/en/docs/oneapi-fpga-add-on/developer-guide/2024-2/unroll-pragma.html
+
+.. |loop_analysis| replace:: Loop Analysis
+.. _loop_analysis: https://www.intel.com/content/www/us/en/docs/oneapi-fpga-add-on/developer-guide/2024-2/loop-analysis.html
+
+.. |fpga_handbook| replace:: Intel® oneAPI FPGA Handbook
+.. _fpga_handbook: https://www.intel.com/content/www/us/en/docs/oneapi-fpga-add-on/developer-guide/2024-2/intel-oneapi-fpga-handbook.html
+
+.. |yocto_layers| replace:: Layers for Yocto* Project
+.. _yocto_layers: https://www.intel.com/content/www/us/en/docs/oneapi-iot-toolkit/get-started-guide-linux/2024-0/adding-oneapi-components-to-yocto-project-builds.html
diff --git a/documentation/library_guide/conf.py b/documentation/library_guide/conf.py
@@ -41,6 +41,7 @@
 
 rst_epilog = """
 .. include:: /variables.txt
+.. include:: /common_cross_document_links.txt
 """
 
 # -- General configuration ---------------------------------------------------

diff --git a/documentation/library_guide/introduction.rst b/documentation/library_guide/introduction.rst
@@ -64,9 +64,7 @@ include the corresponding C++ standard header files and use the ``std`` namespac
 
 Follow the steps below to build your code with |onedpl_short|:
 
-#. To build with the |dpcpp_cpp|, see the `Get Started with the Intel® oneAPI DPC++/C++ Compiler
-   <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/get-started-guide/current/overview.html>`_
-   for details.
+#. To build with the |dpcpp_cpp|, see the |dpcpp_gsg|_ for details.
 #. Set the environment variables for |onedpl_short| and |onetbb_short|.
 
 Below is an example of a command line used to compile code that contains |onedpl_short| parallel algorithms

diff --git a/documentation/library_guide/introduction/onedpl_gsg.rst b/documentation/library_guide/introduction/onedpl_gsg.rst
@@ -1,8 +1,7 @@
 Get Started with the |onedpl_long|
 ##################################
 
-|onedpl_long| (|onedpl_short|) works with the
-`Intel® oneAPI DPC++/C++ Compiler <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/get-started-guide/current/overview.html>`_
+|onedpl_long| (|onedpl_short|) works with the |dpcpp_cpp_with_gsg_link|_
 to provide high-productivity APIs to developers, which can minimize SYCL*
 programming efforts across devices for high performance parallel applications.
 
@@ -14,8 +13,8 @@ programming efforts across devices for high performance parallel applications.
 
 
 For general information about |onedpl_short|, visit the `oneDPL GitHub* repository <https://github.com/oneapi-src/oneDPL>`_,
-or visit the `Intel® oneAPI DPC++ Library Guide <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/overview.html>`_
-and the `Intel® oneAPI DPC++ Library main page <https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-library.html>`_.
+or visit the |onedpl_library_guide|_ and the `Intel® oneAPI DPC++ Library main page
+<https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-library.html>`_.
 
 Quick Start
 ===========
@@ -46,13 +45,17 @@ and use the ``std`` namespace.
 
 CMake Support
 -------------
-`CMake <https://cmake.org/cmake/help/latest/index.html>`_ generates build scripts which can then be used to build and link your application. |onedpl_short| can be added to your project via CMake. 
+`CMake <https://cmake.org/cmake/help/latest/index.html>`_ generates build scripts which can then be used
+to build and link your application. |onedpl_short| can be added to your project via CMake. 
 
-A simple example for Linux is provided below. For more detailed usage and options including details specific to Windows, please look to the `CMake Support Page <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/cmake-support.html>`_.
+A simple example for Linux is provided below. For more detailed usage and options including details specific to Windows,
+please look to the |dpcpp_cmake_support|_.
 
 Simple Example CMake File
 *************************
-To use |onedpl_short| with CMake, create a CMakeLists.txt file for your project's base directory and use `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_ and `target_link_libraries <https://cmake.org/cmake/help/latest/command/target_link_libraries.html>`_ to add oneDPL.
+To use |onedpl_short| with CMake, create a CMakeLists.txt file for your project's base directory and use
+`find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_
+and `target_link_libraries <https://cmake.org/cmake/help/latest/command/target_link_libraries.html>`_ to add oneDPL.
 For example:
 
 .. code:: cpp
@@ -77,7 +80,8 @@ The following is an example CMake invocation which generates build scripts for t
 
 Example Build Command
 *********************
-Once build scripts have been generated for your desired configuration following the instruction above, a `build command <https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project>`_ can be issued to build your project:
+Once build scripts have been generated for your desired configuration following the instruction above, a `build command
+<https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project>`_ can be issued to build your project:
 
 .. code:: cpp
 
@@ -203,15 +207,17 @@ Find More
 
    * - Resource Link
      - Description
-   * - `Intel® oneAPI DPC++ Library Guide <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/overview.html>`_
+   * - |onedpl_library_guide|_
      - Refer to the |onedpl_short| guide for  more in depth information.
    * - `System Requirements <https://www.intel.com/content/www/us/en/developer/articles/system-requirements/intel-oneapi-dpcpp-system-requirements.html>`_
      - Check system requirements before you install |onedpl_short|.
-   * - `Intel® oneAPI DPC++ Library Release Notes <https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-dpcpp-library-release-notes.html>`_
+   * - `Intel® oneAPI DPC++ Library Release Notes
+       <https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-dpcpp-library-release-notes.html>`_
      - Check the release notes to learn about updates in the latest release.
    * - `oneDPL Samples <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneDPL>`_
      - Learn how to use |onedpl_short| with samples.
-   * - `Layers for Yocto* Project <https://www.intel.com/content/www/us/en/docs/oneapi-iot-toolkit/get-started-guide-linux/current/adding-oneapi-components-to-yocto-project-builds.html>`_
+   * - |yocto_layers|_
      - Add oneAPI components to a Yocto project build using the meta-intel layers.
    * - `oneAPI Samples Catalog <https://oneapi-src.github.io/oneAPI-samples/>`_
-     - Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub*). These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs.
+     - Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub*).
+       These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs.
diff --git a/documentation/library_guide/macros.rst b/documentation/library_guide/macros.rst
@@ -55,9 +55,7 @@ Macro                              Description
 ``PSTL_USE_NONTEMPORAL_STORES``    This macro enables the use of ``#pragma vector nontemporal``
                                    for write-only data when algorithms such as ``std::copy``, ``std::fill``, etc.,
                                    are executed with unsequenced policies.
-                                   For further details about the pragma,
-                                   see the `vector page in the Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference
-                                   <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/current/vector.html>`_.
+                                   For further details about the pragma, see the |vector_pragma|_.
                                    If the macro evaluates to a non-zero value,
                                    the use of ``#pragma vector nontemporal`` is enabled.
                                    By default, the macro is not defined.

diff --git a/documentation/library_guide/onedpl_gsg.rst b/documentation/library_guide/onedpl_gsg.rst
@@ -1,8 +1,7 @@
 Get Started with the |onedpl_long|
 ##################################
 
-|onedpl_long| (|onedpl_short|) works with the
-`Intel® oneAPI DPC++/C++ Compiler <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/get-started-guide/current/overview.html>`_
+|onedpl_long| (|onedpl_short|) works with the |dpcpp_cpp_with_gsg_link|_
 to provide high-productivity APIs to developers, which can minimize SYCL*
 programming efforts across devices for high performance parallel applications.
 
@@ -14,8 +13,8 @@ programming efforts across devices for high performance parallel applications.
 
 
 For general information about |onedpl_short|, visit the `oneDPL GitHub* repository <https://github.com/oneapi-src/oneDPL>`_,
-or visit the `Intel® oneAPI DPC++ Library Guide <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/overview.html>`_
-and the `Intel® oneAPI DPC++ Library main page <https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-library.html>`_.
+or visit the |onedpl_library_guide|_ and the `Intel® oneAPI DPC++ Library main page
+<https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-library.html>`_.
 
 Quick Start
 ===========
@@ -46,13 +45,17 @@ and use the ``std`` namespace.
 
 CMake Support
 -------------
-`CMake <https://cmake.org/cmake/help/latest/index.html>`_ generates build scripts which can then be used to build and link your application. |onedpl_short| can be added to your project via CMake. 
+`CMake <https://cmake.org/cmake/help/latest/index.html>`_ generates build scripts which can then be used
+to build and link your application. |onedpl_short| can be added to your project via CMake. 
 
-A simple example for Linux is provided below. For more detailed usage and options including details specific to Windows, please look to the `CMake Support Page <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/cmake-support.html>`_.
+A simple example for Linux is provided below. For more detailed usage and options including details specific to Windows,
+please look to the |dpcpp_cmake_support|_.
 
 Simple Example CMake File
 *************************
-To use |onedpl_short| with CMake, create a CMakeLists.txt file for your project's base directory and use `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_ and `target_link_libraries <https://cmake.org/cmake/help/latest/command/target_link_libraries.html>`_ to add oneDPL.
+To use |onedpl_short| with CMake, create a CMakeLists.txt file for your project's base directory and use
+`find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_
+and `target_link_libraries <https://cmake.org/cmake/help/latest/command/target_link_libraries.html>`_ to add oneDPL.
 For example:
 
 .. code:: cpp
@@ -77,7 +80,8 @@ The following is an example CMake invocation which generates build scripts for t
 
 Example Build Command
 *********************
-Once build scripts have been generated for your desired configuration following the instruction above, a `build command <https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project>`_ can be issued to build your project:
+Once build scripts have been generated for your desired configuration following the instruction above, a `build command
+<https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project>`_ can be issued to build your project:
 
 .. code:: cpp
 
@@ -203,15 +207,17 @@ Find More
 
    * - Resource Link
      - Description
-   * - `Intel® oneAPI DPC++ Library Guide <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/overview.html>`_
+   * - |onedpl_library_guide|_
      - Refer to the |onedpl_short| guide for  more in depth information.
    * - `System Requirements <https://www.intel.com/content/www/us/en/developer/articles/system-requirements/intel-oneapi-dpcpp-system-requirements.html>`_
      - Check system requirements before you install |onedpl_short|.
-   * - `Intel® oneAPI DPC++ Library Release Notes <https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-dpcpp-library-release-notes.html>`_
+   * - `Intel® oneAPI DPC++ Library Release Notes
+       <https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-dpcpp-library-release-notes.html>`_
      - Check the release notes to learn about updates in the latest release.
    * - `oneDPL Samples <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneDPL>`_
      - Learn how to use |onedpl_short| with samples.
-   * - `Layers for Yocto* Project <https://www.intel.com/content/www/us/en/docs/oneapi-iot-toolkit/get-started-guide-linux/current/adding-oneapi-components-to-yocto-project-builds.html>`_
+   * - |yocto_layers|_
      - Add oneAPI components to a Yocto project build using the meta-intel layers.
    * - `oneAPI Samples Catalog <https://oneapi-src.github.io/oneAPI-samples/>`_
-     - Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub*). These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs.
+     - Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub*).
+       These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs.
diff --git a/documentation/library_guide/parallel_api/execution_policies.rst b/documentation/library_guide/parallel_api/execution_policies.rst
@@ -172,10 +172,8 @@ Use it to create customized policy objects or pass directly when invoking an alg
 
    Specifying the unroll factor for a policy enables loop unrolling in the implementation of
    |onedpl_short| algorithms. The default value is 1.
-   To find out how to choose a more precise value, refer to the `unroll Pragma <https://www.intel.com/content/www/us/en/docs/oneapi-fpga-add-on/developer-guide/current/unroll-pragma.html>`_
-   and `Loop Analysis <https://www.intel.com/content/www/us/en/docs/oneapi-fpga-add-on/developer-guide/current/loop-analysis.html>`_ content in
-   the `Intel® oneAPI FPGA Handbook
-   <https://www.intel.com/content/www/us/en/docs/oneapi-fpga-add-on/developer-guide/2024-0/intel-oneapi-fpga-handbook.html>`_.
+   To find out how to choose a more precise value, refer to the |unroll_pragma|_
+   and |loop_analysis|_ content in the |fpga_handbook|_.
 
 The ``make_fpga_policy`` function templates simplify ``fpga_policy`` creation.