Update install and howto section (#504)

* updated the installation instructions, pulling from readme and refining with testing

* my files weren't pushed; trying again

* added an explanation around make

* missing a word

* changed a word for smoother reading

* Update rocThrust-install-overview.rst

* fixed typo

* an initial commit of some readme topics being pulled into the doc

* updated the toc/index and modified the datatype support page a bit

* changed some titles

Author: spolifroni-amd

README.md

@@ -226,7 +226,7 @@ There are two CMake configuration-time options that control random data fed to u
     reproducibility.
 
 * `PRNG_SEEDS`: 1 by default, controls repeatable dataset seeds.
-  * This is a CMake formatted (semicolon delimited) array of 32-bit unsigned integrals. Note that
+  * This is a CMake formatted (semicolon delimited) array of 32-bit unsigned integers. Note that
     semicolons often collide with shell command parsing. We advise escaping the entire CMake CLI
     argument to avoid having the variable pick up quotation marks. For example, pass
     `cmake "-DPRNG_SEEDS=1;2;3;4"` instead of `cmake -DPRNG_SEEDS="1;2;3;4"` (these cases differ in
@@ -270,16 +270,19 @@ make -j4
 ```
 
 ## HIPSTDPAR
+
 rocThrust also hosts the header files for [HIPSTDPAR](https://rocm.blogs.amd.com/software-tools-optimization/hipstdpar/README.html#c-17-parallel-algorithms-and-hipstdpar).
 Within these headers, a great part of the C++ Standard Library parallel algorithms are overloaded so that rocThrust's and rocPRIM's implementations of those algorithms are used when they are invoked with the `parallel_unsequenced_policy` policy.
 When compiling with the proper flags (see [LLVM (AMD's fork) docs](https://github.com/ROCm/llvm-project/blob/rocm-6.2.x/clang/docs/HIPSupport.rst#implementation-driver)[^1] for the complete list), the HIPSTDPAR headers are implicitly included by the compiler, and therefore the execution of these parallel algorithms will be offloaded to AMD devices.
 
 [^1]: Altough currently only AMD's fork of LLVM contains the docs for the [C++ Standard Parallelism Offload Support](https://github.com/ROCm/llvm-project/blob/rocm-6.2.x/clang/docs/HIPSupport.rst#c-standard-parallelism-offload-support-compiler-and-runtime), both of them (the upstream LLVM and AMD's fork) do support it.
 
 ### Install
+
 HIPSTDPAR is currently packaged along rocThrust. The `hipstdpar` package is set up as a virtual package provided by `rocthrust`, so the latter needs to be installed entirely for getting HIPSTDPAR's headers. Conversely, installing the `rocthrust` package will also include HIPSTDPAR's headers in the system.
 
 ### Tests
+
 rocThrust also includes some tests for checking the correct building of HIPSTDPAR implementations. These are located under the [tests/hipstdpar](/test/hipstdpar/) folder. When configuring the project with the `BUILD_TEST` option on, these tests will also be enabled. Additionally, one can configure **only** HIPSTDPAR's tests by disabling `BUILD_TEST` and enabling `BUILD_HIPSTDPAR_TEST`. In general, the following steps can be followed for building and running the tests:
 
 ```sh
@@ -300,6 +303,7 @@ ctest --output-on-failure
 ```
 
 #### Requirements
+
 * [rocPRIM](https://github.com/ROCm/rocPRIM) and [rocThrust](https://github.com/ROCm/rocThrust) libraries
 * [TBB](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onetbb.html) library
   * Notice that oneTBB (oneAPI TBB) may fail to compile when libstdc++-9 or -10 is used, due to them using legacy TBB interfaces that are incompatible with the oneTBB ones (see the [release notes](https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-threading-building-blocks-release-notes.html)).

docs/data-type-support.rst

@@ -8,55 +8,17 @@
 Data type support
 ******************************************
 
-Fundamental types
-=================
-
-
- .. list-table:: Comparison of supported fundamental types of rocThrust and Thrust
-    :header-rows: 1
-    :name: supported-fundamental-types-rocthrust-vs-thrust
-
-    *
-      - Type
-      - rocThrust support
-      - Thrust support
-    *
-      - :code:`int8`
-      - ✅
-      - ✅
-    *
-      - :code:`int16`
-      - ✅
-      - ✅
-    *
-      - :code:`int32`
-      - ✅
-      - ✅
-    *
-      - :code:`int64`
-      - ✅
-      - ✅
-    *
-      - :code:`half` [1]_
-      - ⚠️
-      - ⚠️
-    *
-      - :code:`bfloat16` [1]_
-      - ⚠️
-      - ⚠️
-    *
-      - :code:`float`
-      - ✅
-      - ✅
-    *
-      - :code:`double`
-      - ✅
-      - ✅
-
-Custom types
-============
-
-rocThrust and Thrust support custom, user-defined types, if they provide the interface required by the used functions.
-
-.. rubric:: Footnotes
-.. [1] These types are supported in rocThrust and Thrust, however the host-side hip-implementations of these types miss some functionality, and are mostly intended as storage types to be passed between functions.
+rocThrust supports user-defined custom types as long as an interface for them is provided.
+
+rocThrust and Thrust both support the following fundamental types:
+
+* ``int8``
+* ``int16``
+* ``int32``
+* ``int64``
+* ``float``
+* ``double``
+
+
+Both rocThrust and Thrust also support ``half`` and ``bfloat16``. However, the host-side HIP implementations of these types are missing some functionality. Because of this, ``half`` and ``bfloat16`` should be used only as storage types to be passed between functions.
+

docs/how-to/run-rocThrust-tests-on-multiple-gpus.rst

@@ -0,0 +1,40 @@
+.. meta::
+  :description: Using multiple GPUs for testing
+  :keywords: rocThrust, ROCm, testing, ctest, multiple GPUs, resource-spec
+
+***************************************************
+How to run tests on multiple GPUs
+***************************************************
+
+To run tests on multiple GPUs, you can configure your tests using the ``AMDGPU_TEST_TARGETS`` option or you can use CTest resource allocation.
+
+The ``AMDGPU_TEST_TARGETS`` CTest option lets you specify the families of GPUs on which you want to run your tests. For example, if you have two GPUs from the gfx900 family in your system, you can specify ``-DAMDGPU_TEST_TARGETS=gfx900`` when you configure your test to specify that you only want that family of GPUs to be tested. If you don't set ``AMDGPU_TEST_TARGETS``, the tests will be run on the default device in your system. 
+
+You can use CTest resource allocation to run tests in a distributed manner across multiple GPUs and test multiple product families from one invocation. 
+
+CTest resource allocation requires a resource specification file. You can generate a resource specification file using the ``GenerateResourceSpec.cmake`` utility script. 
+
+After you have cloned the ``rocThrust`` repository and built rocThrust with the ``-DBUILD_TESTS=ON`` option, change directory to the ``build`` directory and run:
+
+.. code:: shell
+
+    ../cmake/GenerateResourceSpec.cmake
+
+This will generate a ``resources.json`` file in the ``build`` directory. Use the ``resources.json`` file in your call to ``ctest``. 
+
+For example, if you have two compatible GPUs in your system, run:
+
+.. code:: shell
+
+    ctest --resource-spec-file ./resources.json --parallel 2
+
+
+.. note:: 
+
+    CTest resource allocation requires CMake 3.16 or later.
+
+
+
+
+
+

docs/how-to/use-rocThrust-in-a-project.rst

@@ -0,0 +1,23 @@
+.. meta::
+  :description: Using rocThrust in a CMake project
+  :keywords: rocThrust, ROCm, cmake, find_package
+
+*******************************************
+How to use rocThrust in a CMake project
+*******************************************
+
+To use rocThrust in your own project, add the following lines to your CMakeLists file:
+
+.. code::  
+
+    # On ROCm rocThrust requires rocPRIM
+    find_package(rocprim REQUIRED CONFIG PATHS "/opt/rocm/rocprim")
+
+    # "/opt/rocm" - default install prefix
+    find_package(rocthrust REQUIRED CONFIG PATHS "/opt/rocm/rocthrust")
+
+    [...]
+
+    # include rocThrust headers and roc::rocprim_hip target
+    target_link_libraries(<your_target> roc::rocthrust)
+

docs/index.rst

@@ -8,26 +8,34 @@
 rocThrust documentation
 ******************************************
 
-rocThrust is a parallel algorithm library. This library has been ported to :doc:`HIP <hip:index>`/:doc:`ROCm <rocm:index>`, which use the :doc:`rocPRIM <rocprim:index>` library. The HIP ported library works on HIP/ROCm platforms. There is no CUDA backend for rocThrust.
+rocThrust is a parallel algorithm library that has been ported to `HIP <https://rocm.docs.amd.com/projects/HIP/en/latest/index.html>`_ and `ROCm <https://rocm.docs.amd.com/en/latest/>`_, and uses the `rocPRIM <https://rocm.docs.amd.com/projects/rocPRIM/en/latest/index.html>`_ library. There is no CUDA backend for rocThrust.
 
-You can access rocThrust code on the `GitHub repository <https://github.com/ROCm/rocThrust>`_.
-
-The documentation is structured as follows:
+The rocThrust public repository is located at `https://github.com/ROCm/rocThrust <https://github.com/ROCm/rocThrust>`_.
 
 .. grid:: 2
-  :gutter: 3
+  :gutter: 3  
 
   .. grid-item-card:: Installation
 
-    * :ref:`install`
+    * :doc:`Prerequisites <install/rocThrust-prerequisites>`
+    * :doc:`Installation overview <install/rocThrust-install-overview>`
+    * :doc:`Installing on Linux <install/rocThrust-install-script>`
+    * :doc:`Installing on Windows <install/rocThrust-rmake-install>`
+    * :doc:`Installing on Linux and Windows with CMake <install/rocThrust-install-with-cmake>`
+
+  .. grid-item-card:: How to
+
+    * :doc:`Add rocThrust to a CMake project <./how-to/use-rocThrust-in-a-project>`
+    * :doc:`Run tests on multiple GPUs <./how-to/run-rocThrust-tests-on-multiple-gpus>`
 
   .. grid-item-card:: API reference
 
+    * :doc:`Using HIPSTDPAR <./reference/rocThrust-hipstdpar>`
     * :ref:`data-type-support`
     * :ref:`bitwise-repro`
     * :ref:`hipgraph-support`
-    * :ref:`api-reference`
     * :ref:`hip-execution-policies`
+    * :ref:`api-reference`
     * :ref:`genindex`
 
 To contribute to the documentation, refer to

docs/install/installing.rst

@@ -0,0 +1,23 @@
+.. meta::
+  :description: rocThrust installation overview 
+  :keywords: install, rocThrust, AMD, ROCm, installation, overview, general
+
+*********************************
+rocThrust installation overview 
+*********************************
+
+The rocThrust source code is available from the `rocThrust GitHub Repository <https://github.com/ROCmSoftwarePlatform/rocThrust>`_. 
+
+The develop branch is the default branch. The develop branch is intended for users who want to preview new features or contribute to the rocThrust code base.
+
+If you don't intend to contribute to the rocThrust code base and won't be previewing features, use a branch that matches the version of ROCm installed on your system.
+
+rocThrust can be built and installed with |install|_ on Linux, |rmake|_ on Windows, or `CMake <./rocThrust-install-with-cmake.html>`_ on Windows and Linux.
+
+.. |install| replace:: ``install``
+.. _install: ./rocThrust-install-script.html
+
+.. |rmake| replace:: ``rmake.py`` 
+.. _rmake: ./rocThrust-rmake-install.html
+
+CMake provides the most flexibility in building and installing rocThrust.

docs/install/rocThrust-install-overview.rst

@@ -0,0 +1,30 @@
+.. meta::
+  :description: Build and install rocThrust with the installation script
+  :keywords: install, building, rocThrust, AMD, ROCm, source code, installation script, Linux
+
+********************************************************************
+Building and installing rocThrust on Linux with the install script
+********************************************************************
+
+You can use the ``install`` script to build and install rocThrust on Linux. You can also use `CMake <./rocThrust-install-with-cmake.html>`_ if you want more build and installation options. 
+
+The ``install`` script is located in the ``rocThrust`` root directory. To build and install rocThrust with the ``install`` script, run:
+
+.. code-block:: shell
+
+  ./install --install
+
+This command will also download and install rocPRIM.
+
+To build rocThrust and generate tar, zip, and debian packages, run:
+
+.. code-block:: shell
+
+  ./install --package
+
+To see a complete list of options, run:
+
+.. code-block:: shell
+
+  ./install --help
+