Cherry pick doc changes into docs/6.1.0 (#131)

* Standardize documentation for ReadtheDocs (#97) * Update link (#112) * update ROCm naming (#95) * Add documentation for supported data types * Update docs/data-type-support.rst Co-authored-by: MKKnorr <MKKnorr@web.de> * Update docs/data-type-support.rst Co-authored-by: MKKnorr <MKKnorr@web.de> * Update docs/data-type-support.rst * Update docs/data-type-support.rst Fix link of ROCm data type support page * Add linkable documentation to opaque device generator state types * Use shell .. code-block:: shellcode-blocks in installing of rst instead of verbatim text * Clarify when and why CMAKE_NO_SYSTEM_FROM_IMPORTED is recommended * Fixed deprecated URLs * Bump rocm-docs-core from 0.38.0 to 0.38.1 in /docs/sphinx (#130) Bumps [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) from 0.38.0 to 0.38.1. - [Release notes](https://github.com/RadeonOpenCompute/rocm-docs-core/releases) - [Changelog](https://github.com/ROCm/rocm-docs-core/blob/develop/CHANGELOG.md) - [Commits](ROCm/rocm-docs-core@v0.38.0...v0.38.1) --- updated-dependencies: - dependency-name: rocm-docs-core dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Sam Wu <sam.wu2@amd.com> Co-authored-by: Lisa <lisajdelaney@gmail.com> Co-authored-by: Istvan Kiss <neon60@gmail.com> Co-authored-by: Istvan Kiss <istvan@streamhpc.com> Co-authored-by: MKKnorr <MKKnorr@web.de> Co-authored-by: Matthias Knorr <matthias@streamhpc.com> Co-authored-by: Gergely Meszaros <gergely@streamhpc.com> Co-authored-by: Lőrinc Serfőző <lorinc@streamhpc.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
ROCm · Apr 17, 2024 · f609f79 · f609f79
1 parent 14d8d15
commit f609f79
Show file tree

Hide file tree

Showing 23 changed files with 151 additions and 41 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -6,7 +6,13 @@
 version: 2
 updates:
   - package-ecosystem: "pip" # See documentation for possible values
-    directory: "/docs/.sphinx" # Location of package manifests
+    directory: "/docs/sphinx" # Location of package manifests
     open-pull-requests-limit: 10
     schedule:
       interval: "daily"
+    labels:
+      - "documentation"
+      - "dependencies"
+      - "ci:docs-only"
+    reviewers:
+      - "samjwu"
diff --git a/.gitignore b/.gitignore
@@ -85,3 +85,7 @@ CMakeLists.txt.user
 
 # Visual Studio / VSCode folders
 .vs*/**/*
+
+# documentation artifacts
+_build/
+.venv
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -6,13 +6,13 @@ version: 2
 sphinx:
    configuration: docs/conf.py
 
-formats: [htmlzip]
+formats: [htmlzip, pdf, epub]
 
 python:
    install:
-   - requirements: docs/.sphinx/requirements.txt
+   - requirements: docs/sphinx/requirements.txt
 
 build:
-   os: ubuntu-20.04
+   os: ubuntu-22.04
    tools:
       python: "3.8"
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -112,7 +112,7 @@ if( CMAKE_CXX_COMPILER MATCHES ".*/hipcc$" )
     string(REGEX MATCH ".mcode\-object\-version" TARGET_ID_SUPPORT ${CXX_OUTPUT})
 endif()
 
-# Verify that hipcc or HIP-aware clang is used on ROCM platform
+# Verify that hipcc or HIP-aware clang is used on ROCM software
 # TODO: Fix VerifyCompiler for Windows
 if (NOT WIN32)
   include(cmake/VerifyCompiler.cmake)

diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ To build our documentation, use the following commands:
 cd hipRAND; cd docs
 
 # Install Python dependencies
-python3 -m pip install -r .sphinx/requirements.txt
+python3 -m pip install -r sphinx/requirements.txt
 
 # Build the documentation
 python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
@@ -36,7 +36,7 @@ You must have the following installed to use hipRAND:
 
 * CMake (3.16 or later)
 * For AMD GPUs:
-  * AMD ROCm platform (5.0.0 or later)
+  * AMD ROCm Software (5.0.0 or later)
   * rocRAND library
 * For NVIDIA GPUs:
   * CUDA Toolkit

diff --git a/cmake/SetupNVCC.cmake b/cmake/SetupNVCC.cmake
@@ -21,7 +21,7 @@
 # SOFTWARE.
 
 # Find HIP package and verify that correct C++ compiler was selected for available
-# platform. On ROCm platform host and device code is compiled by the same compiler.
+# platform. On ROCm software host and device code is compiled by the same compiler.
 # On CUDA host can be compiled by any C++ compiler while device code is compiled
 # by nvcc compiler (CMake's CUDA package handles this).
 

diff --git a/cmake/VerifyCompiler.cmake b/cmake/VerifyCompiler.cmake
@@ -36,8 +36,8 @@ if (BUILD_WITH_LIB STREQUAL "CUDA")
     endif()
 elseif(HIP_COMPILER STREQUAL "clang")
     if(NOT (CMAKE_CXX_COMPILER MATCHES ".*hipcc$" OR CMAKE_CXX_COMPILER MATCHES ".*clang\\+\\+"))
-        message(FATAL_ERROR "On ROCm platform 'hipcc' or HIP-aware Clang must be used as C++ compiler.")
+        message(FATAL_ERROR "On ROCm software 'hipcc' or HIP-aware Clang must be used as C++ compiler.")
     endif()
 else()
-    message(FATAL_ERROR "HIP_COMPILER must be `clang` (AMD ROCm platform)")
+    message(FATAL_ERROR "HIP_COMPILER must be `clang` (AMD ROCm Software)")
 endif()
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,5 +1,6 @@
 /_build/
 /_doxygen/
-/.doxygen/docBin/
-/.doxygen/*.tag
-/.sphinx/_toc.yml
+/doxygen/html/
+/doxygen/xml/
+/doxygen/*.tag
+/sphinx/_toc.yml
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,19 +4,39 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-from rocm_docs import ROCmDocs
 import pathlib
+import re
 import sys
 
+from rocm_docs import ROCmDocs
+
 # We need to add the location of the hiprand Python module to the PATH
 # in order to build the documentation of that module
 docs_dir_path = pathlib.Path(__file__).parent
 python_dir_path = docs_dir_path.parent / 'python' / 'hiprand'
 sys.path.append(str(python_dir_path))
 
-docs_core = ROCmDocs("hipRAND Documentation")
-docs_core.run_doxygen()
+with open('../CMakeLists.txt', encoding='utf-8') as f:
+    match = re.search(r'.*\bset\(hipRAND_VERSION\s+\"?([0-9.]+)[^0-9.]+', f.read())
+    if not match:
+        raise ValueError("VERSION not found!")
+    version_number = match[1]
+left_nav_title = f"hipRAND {version_number} Documentation"
+
+# for PDF output on Read the Docs
+project = "hipRAND Documentation"
+author = "Advanced Micro Devices, Inc."
+copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
+version = version_number
+release = version_number
+
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(left_nav_title)
+docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml")
 docs_core.setup()
 
+external_projects_current_project = "hiprand"
+
 for sphinx_var in ROCmDocs.SPHINX_VARS:
     globals()[sphinx_var] = getattr(docs_core, sphinx_var)
diff --git a/docs/data-type-support.rst b/docs/data-type-support.rst
@@ -0,0 +1,6 @@
+Data type support
+******************************************
+
+hipRAND's data type support is matching cuRAND's data type support. On AMD hardware, the backend is provided by rocRAND. The detailed description, which includes a comparison to cuRAND's data type support, can be found at :doc:`rocRAND's data type support page.<rocrand:data-type-support>`
+
+You can find the ROCm data type support summary at :doc:`Supported data types in ROCm<rocm:about/compatibility/data-type-support>`
diff --git a/docs/.doxygen/Doxyfile → docs/doxygen/Doxyfile b/docs/.doxygen/Doxyfile → docs/doxygen/Doxyfile
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = docBin
+OUTPUT_DIRECTORY       = .
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -774,7 +774,6 @@ WARN_LOGFILE           =
 
 INPUT = \
     mainpage.dox \
-    hipranddevice.dox \
     hiprandhost.dox \
     hiprandhostcpp.dox \
     ../../library/include/hiprand
@@ -2043,7 +2042,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = "__cplusplus=201103L" "HIPRAND_DOXYGEN=1" "HIPRANDAPI=" "FQUALIFIERS=" "QUALIFIERS="
+PREDEFINED             = "__host__=" "__cplusplus=201103L" "HIPRAND_DOXYGEN=1" "HIPRANDAPI=" "FQUALIFIERS=" "QUALIFIERS="
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

diff --git a/docs/.doxygen/hipranddevice.dox → docs/doxygen/hipranddevice.dox b/docs/.doxygen/hipranddevice.dox → docs/doxygen/hipranddevice.dox
diff --git a/docs/.doxygen/hiprandhost.dox → docs/doxygen/hiprandhost.dox b/docs/.doxygen/hiprandhost.dox → docs/doxygen/hiprandhost.dox
diff --git a/docs/.doxygen/hiprandhostcpp.dox → docs/doxygen/hiprandhostcpp.dox b/docs/.doxygen/hiprandhostcpp.dox → docs/doxygen/hiprandhostcpp.dox
diff --git a/docs/.doxygen/mainpage.dox → docs/doxygen/mainpage.dox b/docs/.doxygen/mainpage.dox → docs/doxygen/mainpage.dox
@@ -13,7 +13,7 @@ The hipRAND project provides wrappers which allow users to write code for either
 
 The hipRAND library is a wrapper library which allows users to easily port CUDA applications
 that use the cuRAND library to the [HIP](https://github.com/ROCm-Developer-Tools/HIP) layer.
-In a [ROCm](https://rocm.github.io/) environment hipRAND uses rocRAND, however in a CUDA environment
-cuRAND is used instead.
+In a ROCm environment hipRAND uses rocRAND, however in a CUDA environment cuRAND is used
+instead.
 
 */
diff --git a/docs/installing.rst b/docs/installing.rst
@@ -10,17 +10,23 @@ This chapter describes how to obtain hipRAND. There are two main methods: the ea
 Prebuilt Packages
 -----------------
 
-Installing the prebuilt hipRAND packages requires a ROCm-enabled platform. See the `ROCm documentation <https://docs.amd.com/>`_ for more information. After installing ROCm or enabling the ROCm repositories, hipRAND can be obtained using the system package manager.
+Installing the prebuilt hipRAND packages requires a ROCm-enabled platform. See the `ROCm documentation <https://rocm.docs.amd.com/>`_ for more information. After installing ROCm or enabling the ROCm repositories, hipRAND can be obtained using the system package manager.
 
-For Ubuntu and Debian::
+For Ubuntu and Debian:
+
+.. code-block:: shell
 
     sudo apt-get install hiprand
 
-For CentOS::
+For CentOS:
+
+.. code-block:: shell
 
     sudo yum install hiprand
 
-For SLES::
+For SLES:
+
+.. code-block:: shell
 
     sudo dnf install hiprand
 
@@ -34,10 +40,10 @@ Requirements
 
 To build hipRAND, CMake version 3.10 or later is required.
 
-Additionally, to build hipRAND for the ROCm platform, the following software are required:
+Additionally, to build hipRAND for ROCm software, the following software are required:
 
-* AMD ROCm platform (version 5.0.0 or later).
-* `rocRAND <https://github.com/ROCmSoftwarePlatform/rocRAND.git>`_
+* AMD ROCm Software (version 5.0.0 or later).
+* `rocRAND <https://github.com/ROCm/rocRAND.git>`_
 
 To build hipRAND for the CUDA platform instead, the following software is required:
 
@@ -47,14 +53,18 @@ To build hipRAND for the CUDA platform instead, the following software is requir
 Obtaining Sources
 ^^^^^^^^^^^^^^^^^
 
-The hipRAND sources are available from the `hipRAND GitHub Repository <https://github.com/ROCmSoftwarePlatform/hipRAND>`_. Use the branch that matches the system-installed version of ROCm. For example on a system that has ROCm 5.4 installed, use the following command to obtain hipRAND sources::
+The hipRAND sources are available from the `hipRAND GitHub Repository <https://github.com/ROCm/hipRAND>`_. Use the branch that matches the system-installed version of ROCm. For example on a system that has ROCm 5.4 installed, use the following command to obtain hipRAND sources:
 
-    git checkout -b release/rocm-rel-5.4 https://github.com/ROCmSoftwarePlatform/hipRAND.git
+.. code-block:: shell
+
+    git checkout -b release/rocm-rel-5.4 https://github.com/ROCm/hipRAND.git
 
 Building the Library
 ^^^^^^^^^^^^^^^^^^^^
 
-After obtaining the sources and dependencies, hipRAND can be built for the ROCm platform using the installation script::
+After obtaining the sources and dependencies, hipRAND can be built for ROCm software using the installation script::
+
+.. code-block:: shell
 
     cd hipRAND
     ./install --install
@@ -64,7 +74,9 @@ This automatically builds all required dependencies, excluding HIP and Git, and
 Building with CMake
 ^^^^^^^^^^^^^^^^^^^
 
-For a more elaborate installation process, hipRAND can be built manually using CMake. This enables certain configuration options that are not exposed to the ``./install`` script. In general, hipRAND can be built using CMake by configuring as follows::
+For a more elaborate installation process, hipRAND can be built manually using CMake. This enables certain configuration options that are not exposed to the ``./install`` script. In general, hipRAND can be built using CMake by configuring as follows:
+
+.. code-block:: shell
 
     cd hipRAND; mkdir build; cd build
     # Configure the project
@@ -76,7 +88,7 @@ For a more elaborate installation process, hipRAND can be built manually using C
     # Install
     [sudo] make install
 
-Where ``<compiler>>`` should be set to ``hipcc`` on a ROCm platform, or to a regular C++ compiler such as ``g++`` on a CUDA platform.
+Where ``<compiler>>`` should be set to ``hipcc`` or ``amdclang`` on ROCm software, or to a regular C++ compiler such as ``g++`` on a CUDA platform.
 
 * ``BUILD_WITH_LIB`` controls whether to build hipRAND with the rocRAND or cuRAND backend. If set to ``CUDA``, hipRAND will be built using the cuRAND backend. Otherwise, the rocRAND backend will be used.
 * ``BUILD_FORTRAN_WRAPPER`` controls whether to build the Fortran wrapper. Defaults to ``OFF``.
@@ -86,7 +98,9 @@ Where ``<compiler>>`` should be set to ``hipcc`` on a ROCm platform, or to a reg
 * ``ROCRAND_PATH`` specifies a rocRAND install other than the default system installed one.
 * ``DOWNLOAD_ROCRAND`` specifies that rocRAND will be downloaded and installed in the build directory.
 
-If using ``ROCRAND_PATH`` or ``DOWNLOAD_ROCRAND`` and rocRAND is installed on the system in the default location, ``CMAKE_NO_SYSTEM_FROM_IMPORTED=ON`` must be passed.
+If using ``ROCRAND_PATH`` or ``DOWNLOAD_ROCRAND`` and rocRAND is also installed on the system in the default location then ``CMAKE_NO_SYSTEM_FROM_IMPORTED=ON`` should be passed
+when configuring the project.
+Otherwise the headers of rocRAND might be resolved to the system installed version instead of the specified version, leading to errors or missing functionality.
 
 Building the Python API Wrapper
 -------------------------------
@@ -101,19 +115,25 @@ The hipRAND Python API Wrapper requires the following dependencies:
 * NumPy (will be installed automatically as a dependency if necessary)
 
 Note: If hipRAND is built from sources but not installed or installed in
-non-standard directory, set the ``ROCRAND_PATH`` or ``HIPRAND_PATH`` environment variable to the path containing ``libhiprand.so``. For example::
+non-standard directory, set the ``ROCRAND_PATH`` or ``HIPRAND_PATH`` environment variable to the path containing ``libhiprand.so``. For example:
+
+.. code-block:: shell
 
     export HIPRAND_PATH=~/hipRAND/build/library/
 
 Installing
 ^^^^^^^^^^
 
-The Python hipRAND module can be installed using pip::
+The Python hipRAND module can be installed using pip:
+
+.. code-block:: shell
 
     cd hipRAND/python/hiprand
     pip install .
 
-The tests can be executed as follows::
+The tests can be executed as follows:
+
+.. code-block:: shell
 
     cd hipRAND/python/hiprand
     python tests/hiprand_test.py
diff --git a/docs/license.rst b/docs/license.rst
@@ -0,0 +1,4 @@
+License
+=======
+
+.. include:: ../LICENSE.txt
diff --git a/docs/.sphinx/_toc.yml.in → docs/sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in → docs/sphinx/_toc.yml.in
@@ -4,5 +4,9 @@ root: index
 subtrees:
 - entries:
   - file: installing
+  - file: data-type-support
   - file: cpp_api
   - file: python_api
+- caption: About
+  entries:
+  - file: license
diff --git a/docs/.sphinx/requirements.in → docs/sphinx/requirements.in b/docs/.sphinx/requirements.in → docs/sphinx/requirements.in
diff --git a/docs/.sphinx/requirements.txt → docs/sphinx/requirements.txt b/docs/.sphinx/requirements.txt → docs/sphinx/requirements.txt
@@ -103,7 +103,7 @@ requests==2.28.2
     #   pygithub
     #   sphinx
 rocm-docs-core==0.38.1
-    # via -r docs/.sphinx/requirements.in
+    # via -r requirements.in
 smmap==5.0.0
     # via gitdb
 snowballstemmer==2.2.0

diff --git a/install b/install
@@ -138,7 +138,7 @@ fi
 #   BUILD_BENCHMARK - off by default.
 #
 # ! IMPORTANT !
-# On ROCm platform set C++ compiler to HIPCC. You can do it by adding 'CXX=<path-to-hipcc>'
+# On ROCm software set C++ compiler to HIPCC. You can do it by adding 'CXX=<path-to-hipcc>'
 # before 'cmake' or setting cmake option 'CMAKE_CXX_COMPILER' to path to the HIPCC compiler.
 #