Documentation cherry-pick for 5.6 (#436)

* Updated docs to use the ROCm standard (#418) * Convert Doxygen doc to Sphinx doc breathe needs to be patched in order to correctly look up the functions. The doc can still be generated but with generated errors within the doc. * Update README.md for Sphinx doc * Update README.md for Sphinx doc * Add svg images to regenerate png * Add comments to distinguish images generated from SVG * Order and organize doc * Remove the mention to CUB * Correct typo, improve style * Add examples to iterators * Explicit dependencies versions for building doc * Correct typos Signed-off-by: v01dxyz <v01dxyz@v01d.xyz> * Remove SVG image directory * Re-enable preprocessing for doxygen `__host__` and `__device__` function attributes are shown in the docs. * Re-enable Doxygen to expand all the macros instead of only the predefined ones. * Add cuda / hip attributes to `cpp_id_attributes` in sphinx. This fixes it erroring out on these attributes. * Add `rocprim::` suffix to all functions/classes name references in the rst docs. They were not working previously because the namespace macros were not expanded by doxygen. * Fix documentation of template overloaded methods with doxygen groups Use doxygen groups as a workaround for breathe failing to find methods that have complex template names, or both templated and non templated overloads. non-resolved problem: The `ropcrim::` prefix is not appended to the object names, contrary to the ones generated by the other directives. * Simplify macros for Doxygen * keep only one pre-defined variable to indicate Doxygen preprocessor * isolate macro definitions for Doxygen (only one ifndef instead of one per problematic macro) * Organize conf.py Gather the html options. * Correct typo * Clean Doxyfile Remove commented declarations * Render function parameters as a HTML list Ameliorate how the function signatures are rendered by using HTML list instead of one big single line signature. It is a hack since it mixes span elements with div elements side by side which is not good HTML. Furthermore, this translator would possibly need maintenance if Sphinx introduces breaking changes to the base Translator. * Simplify custom CSS * Remove documentation images Those two images were not particularly relevant and well polished. There were a logo and a draft schema to visualise the different GPU scopes. * Revert deletion of DOXYGEN_SHOULD_SKIP_THIS * Populate doxygen groups for intrinsics * Correct typo Delete duplicate title for a section that was displaced to another file * Rename ops directories * Rename filename/title for summary of the ops * Fixed rebase in config.hpp * Updated docs to the ROCm standard * Updated style and copyright date * Removed docs from top-level gitignore * Removed redundant requirements.txt * Updated CHANGELOG.md * Updated gitignore * Updated Changelog.md * Rebase fix * Updated docs/.gitignore * Added Acknowledgements --------- Signed-off-by: v01dxyz <v01dxyz@v01d.xyz> Co-authored-by: v01dxyz <v01dxyz@v01d.xyz> Co-authored-by: Gergely Meszaros <gergely@streamhpc.com> * Add dependabot config and pin rocm-docs-core (#420) * Update dependabot config (#421) Co-authored-by: samjwu <samjwu@users.noreply.github.com> * Bump rocm-docs-core from 0.2.0 to 0.7.1 in /docs/.sphinx (#425) Bumps [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) from 0.2.0 to 0.7.1. - [Release notes](https://github.com/RadeonOpenCompute/rocm-docs-core/releases) - [Changelog](https://github.com/RadeonOpenCompute/rocm-docs-core/blob/develop/CHANGELOG.md) - [Commits](https://github.com/RadeonOpenCompute/rocm-docs-core/commits/v0.7.1) --- updated-dependencies: - dependency-name: rocm-docs-core dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Update version string (#426) * Fix typo * Update documentation requirements (#429) Co-authored-by: samjwu <samjwu@users.noreply.github.com> * Bump rocm-docs-core from 0.11.0 to 0.13.1 in /docs/.sphinx (#435) Bumps [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) from 0.11.0 to 0.13.1. - [Release notes](https://github.com/RadeonOpenCompute/rocm-docs-core/releases) - [Changelog](https://github.com/RadeonOpenCompute/rocm-docs-core/blob/develop/CHANGELOG.md) - [Commits](ROCm/rocm-docs-core@v0.11.0...v0.13.1) --- updated-dependencies: - dependency-name: rocm-docs-core dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump requests from 2.28.2 to 2.31.0 in /docs/.sphinx (#430) Bumps [requests](https://github.com/psf/requests) from 2.28.2 to 2.31.0. - [Release notes](https://github.com/psf/requests/releases) - [Changelog](https://github.com/psf/requests/blob/main/HISTORY.md) - [Commits](psf/requests@v2.28.2...v2.31.0) --- updated-dependencies: - dependency-name: requests dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --------- Signed-off-by: v01dxyz <v01dxyz@v01d.xyz> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Lőrinc Serfőző <mfep@users.noreply.github.com> Co-authored-by: v01dxyz <v01dxyz@v01d.xyz> Co-authored-by: Gergely Meszaros <gergely@streamhpc.com> Co-authored-by: Sam Wu <swm1000@hotmail.com> Co-authored-by: samjwu <samjwu@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Sam Wu <sam.wu2@amd.com>
ROCm · May 31, 2023 · 687d624 · 687d624
1 parent d8d795d
commit 687d624
Show file tree

Hide file tree

Showing 77 changed files with 1,178 additions and 326 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/docs/.sphinx" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
diff --git a/.gitignore b/.gitignore
@@ -1,12 +1,6 @@
 ### Build dirs ###
 build/
 
-### Docs dirs ###
-doc/html/
-doc/xml/
-doc/latex/
-doc/*.tag
-
 # Created by https://www.gitignore.io/api/c++,cmake
 
 ### C++ ###

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -26,6 +26,7 @@ include:
     file:
       - /defaults.yaml
       - /deps-cmake.yaml
+      - /deps-docs.yaml
       - /deps-rocm.yaml
       - /deps-vcpkg.yaml
       - /gpus-rocm.yaml
@@ -352,21 +353,9 @@ test:deb:
 
 test:docs:
   stage: test
-  extends: .rules:test
-  image: sphinxdoc/sphinx-latexpdf:latest
-  needs: []
-  before_script:
-    - apt-get update -qq
-    - apt-get install -y -qq doxygen
-    - pip3 install --user -r $CI_PROJECT_DIR/docs/requirements.txt
-  script:
-    - cd docs
-    - make
-  artifacts:
-    paths:
-      - $CI_PROJECT_DIR/docs/_build
-      - $CI_PROJECT_DIR/docs/docBin
-    expire_in: 1 week
+  extends:
+    - .rules:test
+    - .build:docs
 
 .benchmark-base:
   stage: benchmark

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,14 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+   configuration: docs/conf.py
+
+formats: [htmlzip]
+
+python:
+   version: "3.8"
+   install:
+   - requirements: docs/.sphinx/requirements.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ Full documentation for rocPRIM is available at [https://rocprim.readthedocs.io/e
 ### Changed
 - Improved the performance of `block_radix_sort` and `device_radix_sort`.
 - Improved the performance of `device_merge_sort`.
+- Updated `docs` directory structure to match the standard of [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core). Contributed by: [v01dXYZ](https://github.com/v01dXYZ).
 ### Known Issues
 - Disabled GPU error messages relating to incorrect warp operation usage with Navi GPUs on Windows, due to GPU printf performance issues on Windows.
 - When `ROCPRIM_DISABLE_LOOKBACK_SCAN` is set, `device_scan` fails for input sizes bigger than `scan_config::size_limit`, which defaults to `std::numeric_limits<unsigned int>::max()`.

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -110,7 +110,7 @@ if(USE_HIP_CPU)
 endif()
 
 # Setup VERSION
-set(VERSION_STRING "2.10.9")
+set(VERSION_STRING "2.13.0")
 rocm_setup_version(VERSION ${VERSION_STRING})
 
 # Print configuration summary

diff --git a/README.md b/README.md
@@ -237,16 +237,21 @@ should be optimized for gfx803 GCN version, or to `900` for gfx900.
 ## Documentation
 The latest rocPRIM documentation and API description can be found [here](https://rocprim.readthedocs.io/en/latest/).
 
-It can also be build using the following commands
+It can also be built using the following commands:
 
 ```shell
-# go to rocPRIM doc directory
-cd rocPRIM; cd doc
+# Go to rocPRIM docs directory
+cd rocPRIM; cd docs
 
-# run doxygen
-doxygen Doxyfile
+# Install Python dependencies
+python3 -m pip install -r .sphinx/requirements.txt
 
-# open html/index.html
+# Build the documentation
+python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
+
+# For e.g. serve the HTML docs locally
+cd _build/html
+python3 -m http.server
 ```
 
 ## hipCUB

diff --git a/custom.properties b/custom.properties
@@ -1,3 +1,3 @@
 booktitle=rocPRIM API Guide
-spreadsheet.xml=doc/classification-map.xml
+spreadsheet.xml=docs/classification-map.xml
 document.locale=enus
diff --git a/docs/Doxyfile → docs/.doxygen/Doxyfile b/docs/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       =
+OUTPUT_DIRECTORY       = docBin
 
 # 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
@@ -781,7 +781,7 @@ INPUT                  = mainpage.dox \
                          iteratormodule.dox \
                          intrinsicsmodule.dox \
                          glossary.dox \
-                         ../rocprim/include/rocprim
+                         ../../rocprim/include/rocprim
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -837,7 +837,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */detail/*
+EXCLUDE_PATTERNS       =
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -2007,7 +2007,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2047,7 +2047,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             = "DOXYGEN_SHOULD_SKIP_THIS=1"
+PREDEFINED             = "DOXYGEN_SHOULD_SKIP_THIS=1" "DOXYGEN_DOCUMENTATION_BUILD"
 
 # 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/blockmodule.dox b/docs/.doxygen/blockmodule.dox
@@ -0,0 +1,21 @@
+/**
+@brief rocPRIM Block-wide parallel primitives
+@author
+@file
+*/
+
+/**
+ * \defgroup blockmodule Block-wide
+ * \ingroup primitivesmodule
+ *
+ */
+
+/**
+ * \defgroup blockmodule_warp_load_functions
+ * \ingroup blockmodule
+ */
+
+/**
+ * \defgroup blockmodule_warp_store_functions
+ * \ingroup blockmodule
+ */
diff --git a/docs/devicemodule.dox → docs/.doxygen/devicemodule.dox b/docs/devicemodule.dox → docs/.doxygen/devicemodule.dox
diff --git a/docs/glossary.dox → docs/.doxygen/glossary.dox b/docs/glossary.dox → docs/.doxygen/glossary.dox
diff --git a/docs/.doxygen/intrinsicsmodule.dox b/docs/.doxygen/intrinsicsmodule.dox
@@ -0,0 +1,19 @@
+/**
+@brief rocPRIM intrinsic functions.
+@author
+@file
+*/
+
+/**
+ * \defgroup intrinsicsmodule Intrinsic functions
+ */
+
+/**
+ * \defgroup intrinsicsmodule_flat_id
+ * \ingroup intrinsicsmodule
+ */
+
+/**
+ * \defgroup intrinsicsmodule_warp_id
+ * \ingroup intrinsicsmodule
+ */
diff --git a/docs/iteratormodule.dox → docs/.doxygen/iteratormodule.dox b/docs/iteratormodule.dox → docs/.doxygen/iteratormodule.dox
diff --git a/docs/mainpage.dox → docs/.doxygen/mainpage.dox b/docs/mainpage.dox → docs/.doxygen/mainpage.dox
diff --git a/docs/primitivesmodule.dox → docs/.doxygen/primitivesmodule.dox b/docs/primitivesmodule.dox → docs/.doxygen/primitivesmodule.dox
diff --git a/docs/utilsmodule.dox → docs/.doxygen/utilsmodule.dox b/docs/utilsmodule.dox → docs/.doxygen/utilsmodule.dox
diff --git a/docs/warpmodule.dox → docs/.doxygen/warpmodule.dox b/docs/warpmodule.dox → docs/.doxygen/warpmodule.dox
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,9 @@
+/_build/
+/_doxygen/
+/_images/
+/_static/
+/_templates/
+/.doxygen/docBin
+/.doxygen/rocPRIM.tag
+/.sphinx/_toc.yml
+/api
diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in
@@ -0,0 +1,14 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+root: index
+subtrees:
+  - entries:
+    - file: intro
+    - file: ops_summary
+    - file: device_ops/index
+    - file: block_ops/index
+    - file: warp_ops/index
+    - file: thread_ops
+    - file: iterators
+    - file: intrinsics
+    - file: glossary
diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in
@@ -0,0 +1 @@
+rocm-docs-core==0.13.1
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
@@ -0,0 +1,145 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+accessible-pygments==0.0.3
+    # via pydata-sphinx-theme
+alabaster==0.7.13
+    # via sphinx
+babel==2.12.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.11.2
+    # via pydata-sphinx-theme
+breathe==4.34.0
+    # via rocm-docs-core
+certifi==2022.12.7
+    # via requests
+cffi==1.15.1
+    # via
+    #   cryptography
+    #   pynacl
+charset-normalizer==3.1.0
+    # via requests
+click==8.1.3
+    # via sphinx-external-toc
+cryptography==40.0.2
+    # via pyjwt
+deprecated==1.2.13
+    # via pygithub
+docutils==0.19
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+fastjsonschema==2.16.3
+    # via rocm-docs-core
+gitdb==4.0.10
+    # via gitpython
+gitpython==3.1.31
+    # via rocm-docs-core
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via
+    #   myst-parser
+    #   sphinx
+linkify-it-py==1.0.3
+    # via myst-parser
+markdown-it-py==2.2.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.2
+    # via jinja2
+mdit-py-plugins==0.3.5
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser[linkify]==1.0.0
+    # via rocm-docs-core
+packaging==23.0
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+pycparser==2.21
+    # via cffi
+pydata-sphinx-theme==0.13.3
+    # via
+    #   rocm-docs-core
+    #   sphinx-book-theme
+pygithub==1.58.1
+    # via rocm-docs-core
+pygments==2.14.0
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt[crypto]==2.6.0
+    # via pygithub
+pynacl==1.5.0
+    # via pygithub
+pyyaml==6.0
+    # via
+    #   myst-parser
+    #   rocm-docs-core
+    #   sphinx-external-toc
+requests==2.31.0
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core==0.13.1
+    # via -r requirements.in
+smmap==5.0.0
+    # via gitdb
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.4
+    # via beautifulsoup4
+sphinx==5.3.0
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   rocm-docs-core
+    #   sphinx-book-theme
+    #   sphinx-copybutton
+    #   sphinx-design
+    #   sphinx-external-toc
+    #   sphinx-notfound-page
+sphinx-book-theme==1.0.1
+    # via rocm-docs-core
+sphinx-copybutton==0.5.1
+    # via rocm-docs-core
+sphinx-design==0.4.1
+    # via rocm-docs-core
+sphinx-external-toc==0.3.1
+    # via rocm-docs-core
+sphinx-notfound-page==0.8.3
+    # via rocm-docs-core
+sphinxcontrib-applehelp==1.0.4
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+typing-extensions==4.5.0
+    # via pydata-sphinx-theme
+uc-micro-py==1.0.1
+    # via linkify-it-py
+urllib3==1.26.15
+    # via requests
+wrapt==1.15.0
+    # via deprecated