Documentation cherry-pick for 5.6 (#251)

* Updated docs to use the ROCm standard (#236) * HTML documentation uses rocm-docs-core template * Updated changelog.md * Removed redundant inputs from doxyfile * Reverted file patterns in Doxyfile * Updated .gitignore * Add dependabot config and Pin rocm-docs-core (#237) * Add dependabot config and pin rocm-docs-core * pin exhale --------- Co-authored-by: samjwu <[email protected]> * Fix dependabot file structure (#238) Co-authored-by: samjwu <[email protected]> * Update dependabot config (#239) Co-authored-by: samjwu <[email protected]> * Update version string (#242) * Update documentation requirements - replaces exhale with doxysphinx (#245) * Bump requests from 2.28.2 to 2.31.0 in /docs/.sphinx (#246) 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] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump rocm-docs-core[api_reference] in /docs/.sphinx (#250) Bumps [rocm-docs-core[api_reference]](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[api_reference] dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: Lőrinc Serfőző <[email protected]> Co-authored-by: Sam Wu <[email protected]> Co-authored-by: samjwu <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
ROCm · May 31, 2023 · dd26e47 · dd26e47
1 parent cf03c9f
commit dd26e47
Show file tree

Hide file tree

Showing 21 changed files with 311 additions and 425 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/_build/
-
-### Docs dirs ###
-/docs/docBin/
-/docs/api/
-/docs/hipCUB.tag
 
 # Created by https://www.gitignore.io/api/c++,cmake
 
@@ -51,7 +45,6 @@ CMakeFiles
 CMakeScripts
 Testing
 Makefile
-!/docs/Makefile
 cmake_install.cmake
 install_manifest.txt
 compile_commands.json

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-nvcc.yaml
         - /gpus-rocm.yaml
@@ -390,16 +391,9 @@ test:nvcc_install:
 
 test:doc:
   stage: test
-  image: sphinxdoc/sphinx-latexpdf
   extends:
     - .rules:test
-  needs: []
-  before_script:
-    - apt-get update
-    - apt-get install -y -qq doxygen
-    - pip3 install sphinx_rtd_theme breathe exhale
-  script:
-    - $CI_PROJECT_DIR/docs/run_doc.sh
+    - .build:docs
 
 scheduled-check-changes:
   extends: .rules:scheduled-check-changes
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,20 @@
+# 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, pdf, epub]
+
+python:
+   install:
+   - requirements: docs/.sphinx/requirements.txt
+
+build:
+   os: ubuntu-20.04
+   tools:
+      python: "3.8"
+   apt_packages:
+     - "doxygen"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ See README.md on how to build the hipCUB documentation using Doxygen.
 ### Changed
 - CUB backend references CUB and Thrust version 1.17.2.
 - Improved benchmark coverage of `BlockScan` by adding `ExclusiveScan`, benchmark coverage of `BlockRadixSort` by adding `SortBlockedToStriped`, and benchmark coverage of `WarpScan` by adding `Broadcast`.
+- Updated `docs` directory structure to match the standard of [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core).
 ### Known Issues
 - `BlockRadixRankMatch` is currently broken under the rocPRIM backend.
 - `BlockRadixRankMatch` with a warp size that does not exactly divide the block size is broken under the CUB backend.

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -111,7 +111,7 @@ endif()
 include(cmake/Dependencies.cmake)
 
 # Setup VERSION
-set(VERSION_STRING "2.10.12")
+set(VERSION_STRING "2.13.1")
 rocm_setup_version(VERSION ${VERSION_STRING})
 
 # Print configuration summary

diff --git a/README.md b/README.md
@@ -181,13 +181,18 @@ cd hipCUB; cd build
 ## Building Documentation
 
 ```shell
-# go to hipCUB docs directory
+# Go to the hipCUB docs directory
 cd hipCUB; cd docs
 
-# run doxygen and sphinx
-./run_doc.sh
+# Install required pip packages
+python3 -m pip install -r .sphinx/requirements.txt
 
-# open docBin/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
 ```
 
 ## Support

diff --git a/docs/Doxyfile → docs/.doxygen/Doxyfile b/docs/Doxyfile → docs/.doxygen/Doxyfile
@@ -51,7 +51,7 @@ PROJECT_BRIEF          =
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = ./rocm.jpg
+PROJECT_LOGO           =
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -118,7 +118,18 @@ REPEAT_BRIEF           = YES
 # the entity):The $name class, The $name widget, The $name file, is, provides,
 # specifies, contains, represents, a, an and the.
 
-ABBREVIATE_BRIEF       =
+
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
 
 # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
 # doxygen will generate a detailed section even if there is only a brief
@@ -216,7 +227,7 @@ SEPARATE_MEMBER_PAGES  = NO
 # uses this value to replace tabs by spaces in code fragments.
 # Minimum value: 1, maximum value: 16, default value: 4.
 
-TAB_SIZE               = 8
+TAB_SIZE               = 4
 
 # This tag can be used to specify a number of aliases that act as commands in
 # the documentation. An alias has the form:
@@ -770,22 +781,8 @@ WARN_LOGFILE           =
 # directories like /usr/src/myproject. Separate the files or directories with
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
-#mainpage.dox \ 
-INPUT                  = ../hipcub/include/hipcub \
-                         ../hipcub/include/hipcub/device \
-                         ../hipcub/include/hipcub/iterator \
-                         ../hipcub/include/hipcub/thread \
-                         ../hipcub/include/hipcub/warp \
-                         ../hipcub/include/hipcub/block \
-                         ../hipcub/include/hipcub/backend \
-                         ../hipcub/include/hipcub/backend/cub \
-                         ../hipcub/include/hipcub/backend/cub/device \
-                         ../hipcub/include/hipcub/backend/rocprim \
-                         ../hipcub/include/hipcub/backend/rocprim/device \
-                         ../hipcub/include/hipcub/backend/rocprim/iterator \
-                         ../hipcub/include/hipcub/backend/rocprim/thread \
-                         ../hipcub/include/hipcub/backend/rocprim/warp \
-                         ../hipcub/include/hipcub/backend/rocprim/block
+
+INPUT                  = ../../hipcub/include/hipcub
 
 # 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
@@ -1109,7 +1106,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_HEADER            =
+HTML_HEADER            = ../_doxygen/header.html
 
 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1119,7 +1116,7 @@ HTML_HEADER            =
 # that doxygen normally uses.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_FOOTER            =
+HTML_FOOTER            = ../_doxygen/footer.html
 
 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
 # sheet that is used by each HTML page. It can be used to fine-tune the look of
@@ -1131,7 +1128,7 @@ HTML_FOOTER            =
 # obsolete.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_STYLESHEET        =
+HTML_STYLESHEET        = ../_doxygen/stylesheet.css
 
 # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined
 # cascading style sheets that are included after the standard style sheets
@@ -1144,7 +1141,7 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = ../_doxygen/extra_stylesheet.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1430,7 +1427,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NONE
+GENERATE_TREEVIEW      = NO
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.
@@ -1485,7 +1482,7 @@ FORMULA_TRANSPARENT    = YES
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-USE_MATHJAX            = NO
+USE_MATHJAX            = YES
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. See the MathJax site (see:
@@ -1661,7 +1658,7 @@ COMPACT_LATEX          = NO
 # The default value is: a4.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 
 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
 # that should be included in the LaTeX output. The package can be specified just
@@ -2033,7 +2030,7 @@ SEARCH_INCLUDES        = YES
 # preprocessor.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           = ../hipcub/include/hipcub/
+INCLUDE_PATH           = ../../hipcub/include/hipcub/
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -2097,7 +2094,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       = hipCUB.tag
+GENERATE_TAGFILE       = docBin/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
@@ -2173,7 +2170,7 @@ DOT_NUM_THREADS        = 0
 # The default value is: Helvetica.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_FONTNAME           =
+DOT_FONTNAME           = Helvetica
 
 # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
 # dot graphs.
@@ -2315,7 +2312,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.
@@ -2327,7 +2324,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/.gitignore b/docs/.gitignore
@@ -0,0 +1,8 @@
+/_build/
+/_images/
+/_static/
+/_templates/
+/.doxygen/docBin
+/.doxygen/hipCUB.tag
+/.sphinx/_toc.yml
+/api
diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in
@@ -0,0 +1,6 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+root: index
+subtrees:
+  - entries:
+    - file: .doxygen/docBin/html/index
diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in
@@ -0,0 +1 @@
+rocm-docs-core[api_reference]==0.13.1