From 72e27e8ce7fcc3268d1b7c824e741105f35e1692 Mon Sep 17 00:00:00 2001 From: srawat <120587655+SwRaw@users.noreply.github.com> Date: Wed, 31 Jan 2024 20:07:15 +0530 Subject: [PATCH] rocRAND documentation restructure (#421) --- docs/api-reference-home.rst | 16 ++++++ docs/conf.py | 6 ++- docs/{cpp_api.rst => cpp-api.rst} | 14 ++++-- docs/curand-compatibility.rst | 28 +++++++++++ docs/doxygen/Doxyfile | 8 +-- docs/index.rst | 50 ++++++++++++------- docs/installing.rst | 18 ++++--- ...ammers_guide.rst => programmers-guide.rst} | 30 +++-------- docs/{python_api.rst => python-api.rst} | 8 ++- docs/sphinx/_toc.yml.in | 17 ++++--- docs/sphinx/requirements.txt | 26 ++++++++-- docs/what-is-rocrand.rst | 20 ++++++++ library/src/fortran/README.md | 6 +-- 13 files changed, 176 insertions(+), 71 deletions(-) create mode 100644 docs/api-reference-home.rst rename docs/{cpp_api.rst => cpp-api.rst} (53%) create mode 100644 docs/curand-compatibility.rst rename docs/{programmers_guide.rst => programmers-guide.rst} (86%) rename docs/{python_api.rst => python-api.rst} (78%) create mode 100644 docs/what-is-rocrand.rst diff --git a/docs/api-reference-home.rst b/docs/api-reference-home.rst new file mode 100644 index 00000000..f1e4b32c --- /dev/null +++ b/docs/api-reference-home.rst @@ -0,0 +1,16 @@ +.. meta:: + :description: rocRAND documentation and API reference library + :keywords: rocRAND, ROCm, API, documentation + +.. _api-reference-home: + +=================== +rocRAND API reference +=================== + +rocRAND APIs are available in the following programming languages: + +* :ref:`C/C++` +* :ref:`Python` + +Here is the :ref:`genindex` for all rocRAND APIs. diff --git a/docs/conf.py b/docs/conf.py index 9573accc..0362d9f2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -5,8 +5,9 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html import pathlib -import re +import shutil import sys +import re from rocm_docs import ROCmDocs @@ -22,6 +23,7 @@ raise ValueError("VERSION not found!") version_number = match[1] left_nav_title = f"rocRAND {version_number} Documentation" +shutil.copy2('../library/src/fortran/README.md', './fortran-api-reference.md') # for PDF output on Read the Docs project = "rocRAND Documentation" @@ -31,9 +33,11 @@ release = version_number external_toc_path = "./sphinx/_toc.yml" +external_projects_current_project = "rocrand" docs_core = ROCmDocs(left_nav_title) docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") +docs_core.enable_api_reference() docs_core.setup() external_projects_current_project = "rocrand" diff --git a/docs/cpp_api.rst b/docs/cpp-api.rst similarity index 53% rename from docs/cpp_api.rst rename to docs/cpp-api.rst index 22462f3a..23f05fa5 100644 --- a/docs/cpp_api.rst +++ b/docs/cpp-api.rst @@ -1,17 +1,23 @@ +.. meta:: + :description: rocRAND documentation and API reference library + :keywords: rocRAND, ROCm, API, documentation + +.. _cpp-api: + =================== -C/C++ API Reference +C/C++ API reference =================== This chapter describes the rocRAND C and C++ API. -Device Functions +Device functions ================ .. doxygengroup:: rocranddevice -C Host API +C host API ========== .. doxygengroup:: rocrandhost -C++ Host API Wrapper +C++ host API wrapper ==================== .. doxygengroup:: rocrandhostcpp diff --git a/docs/curand-compatibility.rst b/docs/curand-compatibility.rst new file mode 100644 index 00000000..75e32b0b --- /dev/null +++ b/docs/curand-compatibility.rst @@ -0,0 +1,28 @@ +.. meta:: + :description: rocRAND documentation and API reference library + :keywords: rocRAND, ROCm, API, documentation, cuRAND + +.. _curand-compatibility: + +==================== +cuRAND compatibility +==================== + +The following table shows which rocRAND generators produce the exact same sequence as the equivalent cuRAND generator when using legacy ordering, given the same seed, number of dimensions, and offset. + +.. table:: cuRAND Compatibility + :widths: auto + + ================= ===================== + Generator Compatible + ================= ===================== + XORWOW No + MRG32K3A No + MTGP32 No + Philox 32x4-10 No + MT19937 No + Sobol32 Yes + Scrambled Sobol32 No + Sobol64 Yes, with same offset + Scrambled Sobol64 No + ================= ===================== \ No newline at end of file diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 5c588984..661f9460 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = rocRAND +PROJECT_NAME = "API library" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -2164,7 +2164,7 @@ TAGFILES = # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = hipRAND.tag +GENERATE_TAGFILE = html/tagfile.xml # If the ALLEXTERNALS tag is set to YES, all external class will be listed in # the class index. If set to NO, only the inherited external classes will be @@ -2380,7 +2380,7 @@ DIRECTORY_GRAPH = YES # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_IMAGE_FORMAT = png +DOT_IMAGE_FORMAT = svg # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to # enable generation of interactive SVG images that allow zooming and panning. @@ -2392,7 +2392,7 @@ DOT_IMAGE_FORMAT = png # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -INTERACTIVE_SVG = NO +INTERACTIVE_SVG = YES # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. diff --git a/docs/index.rst b/docs/index.rst index 80f30675..c155d09a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,23 +1,37 @@ -================== -rocRAND User Guide -================== +.. meta:: + :description: rocRAND documentation and API reference library + :keywords: rocRAND, ROCm, API, documentation -Overview -======== +.. _rocrand-docs-home: -The rocRAND project provides functions that generate pseudo-random and quasi-random numbers. +******************************************************************** +rocRAND documentation +******************************************************************** -The rocRAND library is implemented in the `HIP `_ -programming language and optimised for AMD's latest discrete GPUs. It is designed to run on top -of AMD's Radeon Open Compute `ROCm `_ runtime, but it also works on -CUDA enabled GPUs. -Additionally, the project includes a wrapper library called hipRAND which allows users to easily port -CUDA applications that use cuRAND library to the `HIP `_ -layer. In `ROCm `_ environment hipRAND uses rocRAND, however in CUDA -environment cuRAND is used instead. +Welcome to the rocRAND docs home page! To learn more, see :ref:`what-is-rocrand` -Indices and tables ------------------- +Our documentation is structured as follows: -* :ref:`genindex` -* :ref:`search` +.. grid:: 2 + :gutter: 3 + + .. grid-item-card:: API reference + + * :ref:`cpp-api` + * :ref:`python-api` + * :ref:`curand-compatibility` + * :doc:`API library ` + + .. grid-item-card:: Conceptual + + * :ref:`programmers-guide` + + .. grid-item-card:: Tutorial + + * :ref:`installing` + +Contributing to this documentation +======================================================= + +We welcome collaboration! If you'd like to contribute to our documentation, you can find instructions on our `Contribute to ROCm docs `_ page. Known issues are listed on `GitHub `_. +Licensing information for all ROCm components is listed on our `Licensing `_ page. diff --git a/docs/installing.rst b/docs/installing.rst index a01989fe..a47b9139 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -1,3 +1,9 @@ +.. meta:: + :description: rocRAND documentation and API reference library + :keywords: rocRAND, ROCm, API, documentation + +.. _installing: + ============ Installation ============ @@ -7,7 +13,7 @@ Introduction This chapter describes how to obtain rocRAND. There are two main methods: the easiest way is to install the prebuilt packages from the ROCm repositories. Alternatively, this chapter also describes how to build rocRAND from source. -Prebuilt Packages +Prebuilt packages ----------------- Installing the prebuilt rocRAND packages requires a ROCm-enabled platform. See the `ROCm documentation `_ for more information. After installing ROCm or enabling the ROCm repositories, rocRAND can be obtained using the system package manager. @@ -26,17 +32,17 @@ For SLES:: This will install rocRAND into the ``/opt/rocm`` directory. -Building rocRAND From Source +Building rocRAND from source ---------------------------- -Obtaining Sources +Obtaining sources ^^^^^^^^^^^^^^^^^ The rocRAND sources are available from the `rocRAND GitHub Repository `_. Use the branch that matches the system-installed version of ROCm. For example on a system that has ROCm 5.3 installed, use the following command to obtain rocRAND sources:: git checkout -b rocm-5.3 https://github.com/ROCmSoftwarePlatform/rocRAND.git -Building The Library +Building the library ^^^^^^^^^^^^^^^^^^^^ After obtaining the sources, rocRAND can be built using the installation script:: @@ -46,7 +52,7 @@ After obtaining the sources, rocRAND can be built using the installation script: This automatically builds all required dependencies, excluding HIP and Git, and installs the project to ``/opt/rocm`` if everything went well. See ``./install --help`` for further information. -Building With CMake +Building with CMake ^^^^^^^^^^^^^^^^^^^ For a more elaborate installation process, rocRAND can be built manually using CMake. This enables certain configuration options that are not exposed to the ``./install`` script. In general, rocRAND can be built using CMake by configuring as follows:: @@ -73,7 +79,7 @@ The following configuration options are available, in addition to the built-in C To install rocRAND with a non-standard installation location of ROCm, pass ``-DCMAKE_PREFIX_PATH=`` or set the environment variable ``ROCM_PATH`` to ``path/to/opt/rocm``. -Building the Python API Wrapper +Building the Python API wrapper ------------------------------- Requirements diff --git a/docs/programmers_guide.rst b/docs/programmers-guide.rst similarity index 86% rename from docs/programmers_guide.rst rename to docs/programmers-guide.rst index 9ea334b9..5d23768e 100644 --- a/docs/programmers_guide.rst +++ b/docs/programmers-guide.rst @@ -1,5 +1,11 @@ +.. meta:: + :description: rocRAND documentation and API reference library + :keywords: rocRAND, ROCm, API, documentation + +.. _programmers-guide: + ================== -Programmer's Guide +Programmer's guide ================== Generator types @@ -67,25 +73,3 @@ ThreeFry Sobol The (scrambled) 32- and 64-bit sobol quasi-random number generators generated the result from :math:`d` dimensions by flattening them into the output. The result at offset :math:`n` in memory is generated from offset :math:`n\;\mathrm{mod}\; d` in dimension :math:`\lfloor n / d \rfloor`, where :math:`d` is the generator's number of dimensions. - -cuRAND Compatibility --------------------- - -The following table shows which rocRAND generators produce the exact same sequence as the equivalent cuRAND generator when using legacy ordering, given the same seed, number of dimensions, and offset. - -.. table:: cuRAND Compatibility - :widths: auto - - ================= ===================== - Generator Compatibile - ================= ===================== - XORWOW No - MRG32K3A No - MTGP32 No - Philox 32x4-10 No - MT19937 No - Sobol32 Yes - Scrambled Sobol32 No - Sobol64 Yes, with same offset - Scrambled Sobol64 No - ================= ===================== diff --git a/docs/python_api.rst b/docs/python-api.rst similarity index 78% rename from docs/python_api.rst rename to docs/python-api.rst index e1d57be7..ae7b4c9c 100644 --- a/docs/python_api.rst +++ b/docs/python-api.rst @@ -1,5 +1,11 @@ +.. meta:: + :description: rocRAND documentation and API reference library + :keywords: rocRAND, ROCm, API, documentation + +.. _python-api: + ==================== -Python API Reference +Python API reference ==================== This chapter describes the rocRAND Python module API. diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index fbc24a20..74b87245 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -4,10 +4,13 @@ root: index subtrees: - entries: - file: installing - - file: data-type-support - - file: programmers_guide - - file: cpp_api - - file: python_api - - caption: About - entries: - - file: license + - file: programmers-guide + - file: what-is-rocrand + - file: api-reference-home + title: API reference + subtrees: + - entries: + - file: cpp-api + - file: python-api + - file: curand-compatibility + - file: doxygen/html/index diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt index eb111269..e98a9c14 100644 --- a/docs/sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -25,7 +25,12 @@ cffi==1.15.1 charset-normalizer==3.1.0 # via requests click==8.1.3 - # via sphinx-external-toc + # via + # click-log + # doxysphinx + # sphinx-external-toc +click-log==0.4.0 + # via doxysphinx cryptography==41.0.6 # via pyjwt deprecated==1.2.13 @@ -36,6 +41,8 @@ docutils==0.16 # myst-parser # pydata-sphinx-theme # sphinx +doxysphinx==3.3.7 + # via rocm-docs-core fastjsonschema==2.16.3 # via rocm-docs-core gitdb==4.0.10 @@ -54,6 +61,10 @@ jinja2==3.1.3 # via # myst-parser # sphinx +libsass==0.22.0 + # via doxysphinx +lxml==4.9.4 + # via doxysphinx markdown-it-py==2.2.0 # via # mdit-py-plugins @@ -64,6 +75,8 @@ mdit-py-plugins==0.3.5 # via myst-parser mdurl==0.1.2 # via markdown-it-py +mpire==2.9.0 + # via doxysphinx myst-parser==1.0.0 # via rocm-docs-core numpy==1.24.4 @@ -83,14 +96,17 @@ pygithub==1.58.1 pygments==2.15.1 # via # accessible-pygments + # mpire # pydata-sphinx-theme # sphinx +pyjson5==1.6.5 + # via doxysphinx pyjwt[crypto]==2.6.0 - # via - # pygithub - # pyjwt + # via pygithub pynacl==1.5.0 # via pygithub +pyparsing==3.1.1 + # via doxysphinx pytz==2023.3.post1 # via babel pyyaml==6.0 @@ -143,6 +159,8 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx +tqdm==4.66.1 + # via mpire typing-extensions==4.5.0 # via pydata-sphinx-theme urllib3==1.26.18 diff --git a/docs/what-is-rocrand.rst b/docs/what-is-rocrand.rst new file mode 100644 index 00000000..7b1a1070 --- /dev/null +++ b/docs/what-is-rocrand.rst @@ -0,0 +1,20 @@ +.. meta:: + :description: rocRAND provides functions that generate pseudo-random and quasi-random numbers + :keywords: rocRAND, ROCm, library, API, HIP + +.. _what-is-rocrand: + +================== +What is rocRAND? +================== + +The rocRAND project provides functions that generate pseudo-random and quasi-random numbers. + +The rocRAND library is implemented in the `HIP `_ +programming language and optimised for AMD's latest discrete GPUs. It is designed to run on top +of AMD's Radeon Open Compute `ROCm `_ runtime, but it also works on +CUDA enabled GPUs. +Additionally, the project includes a wrapper library called hipRAND which allows users to easily port +CUDA applications that use cuRAND library to the `HIP `_ +layer. In `ROCm `_ environment hipRAND uses rocRAND, however in CUDA +environment cuRAND is used instead. diff --git a/library/src/fortran/README.md b/library/src/fortran/README.md index 78d6ff93..359ffdc2 100644 --- a/library/src/fortran/README.md +++ b/library/src/fortran/README.md @@ -1,4 +1,4 @@ -# rocRAND Fortran +# Fortran API reference This library provides a pure Fortran interface for the rocRAND API. @@ -6,7 +6,7 @@ This interface is intended to target only Host API functions, and provides a 1:1 the C Host API functions in rocRAND. For documentation of these functions, please refer to the C Host API functions documentation. -## Build and Install +## Build and install The Fortran interface is installed as part of the rocRAND package. Simply add the build option `-DBUILD_FORTRAN_WRAPPER=ON` when configuring cmake, as below: @@ -15,7 +15,7 @@ option `-DBUILD_FORTRAN_WRAPPER=ON` when configuring cmake, as below: cmake -DBUILD_FORTRAN_WRAPPER=ON ../. ``` -## Running Unit Tests +## Running unit tests ``` # Go to rocRAND build directory