rocRAND documentation restructure (#421)

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++<cpp-api>`
+* :ref:`Python<python-api>`
+
+Here is the :ref:`genindex` for all rocRAND APIs.

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"

docs/cpp_api.rst → 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

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
+    =================  =====================

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.

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 <https://github.com/ROCm-Developer-Tools/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 <https://rocm.github.io/>`_ 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 <https://github.com/ROCm-Developer-Tools/HIP>`_
-layer. In `ROCm <https://rocm.github.io/>`_ 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 <doxygen/html/index>`
+
+  .. 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 <https://rocm.docs.amd.com/en/latest/contribute/index.html>`_ page. Known issues are listed on `GitHub <https://github.com/RadeonOpenCompute/ROCm/labels/Verified%20Issue>`_.
+Licensing information for all ROCm components is listed on our `Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.

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 <https://docs.amd.com/>`_ 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 <https://github.com/ROCmSoftwarePlatform/rocRAND>`_. 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=</path/to/opt/rocm/>`` or set the environment variable ``ROCM_PATH`` to ``path/to/opt/rocm``.
 
-Building the Python API Wrapper
+Building the Python API wrapper
 -------------------------------
 
 Requirements

docs/programmers_guide.rst → 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
-    =================  =====================

docs/python_api.rst → 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.

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