Documentation update for Read the Docs

Standard template implementation (#703) Fix Docs static analysis (#708) * remove ref to old script in static analysis * update README with doc build instructions update gitignore with doc artifacts pin rocm-docs-core and add dependabot config (#722) Bump rocm-docs-core from 0.2.0 to 0.5.0 in /docs/.sphinx (#728) Bumps [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core) from 0.2.0 to 0.5.0. - [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.5.0) --- 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 Read the Docs, documentation, and dependabot (#772) * update documentation add version number to documentation rename .sphinx/.doxygen to sphinx/doxygen enable htmlzip, pdf, epub formats when publishing on Read the Docs * add noCI label for dependabot PRs since RTD CI is separate from math lib CI * update rocm-docs-core to v0.13.4 * update README with link to rocm.docs.amd.com
ROCm · Jun 15, 2023 · 40e4731 · 40e4731
1 parent a44e92c
commit 40e4731
Show file tree

Hide file tree

Showing 25 changed files with 275 additions and 509 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,17 @@
+# 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"
+    labels:
+      - "dependencies"
+      - "noCI"
+    reviewers:
+      - "samjwu"
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,13 @@
 # Copyright (c) 2015-2016, NVIDIA CORPORATION. All rights reserved.
-/build
 *.gcov
 /coverage/
+
+# documentation artifacts
+build/
+_build/
+_images/
+_static/
+_templates/
+_toc.yml
+docBin/
+_doxygen/
diff --git a/.jenkins/staticanalysis.groovy b/.jenkins/staticanalysis.groovy
@@ -12,28 +12,6 @@ import java.nio.file.Path
 def runCompileCommand(platform, project, jobName, boolean debug=false)
 {
     project.paths.construct_build_prefix()
-
-    def command = """#!/usr/bin/env bash
-            set -x
-            ${project.paths.project_build_prefix}/docs/run_doc.sh
-            """
-
-    try
-    {
-        platform.runCommand(this, command)
-    }
-    catch(e)
-    {
-        throw e
-    }
-
-    publishHTML([allowMissing: false,
-                alwaysLinkToLastBuild: false,
-                keepAll: false,
-                reportDir: "${project.paths.project_build_prefix}/docs/source/_build/html",
-                reportFiles: "index.html",
-                reportName: "Documentation",
-                reportTitles: "Documentation"])
 }
 
 def runCI = 

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+   os: ubuntu-22.04
+   tools:
+      python: "3.8"
+
+sphinx:
+   configuration: docs/conf.py
+
+formats: [htmlzip, pdf, epub]
+
+python:
+   install:
+   - requirements: docs/sphinx/requirements.txt
diff --git a/README.md b/README.md
@@ -32,7 +32,8 @@ The root of this repository has a helper script 'install.sh' to build and instal
 *  `./install.sh --prefix` -- specify custom path to install RCCL to (default:/opt/rocm)
 
 ## Manual build
-#### To build the library :
+
+### To build the library :
 
 ```shell
 $ git clone https://github.com/ROCmSoftwarePlatform/rccl.git
@@ -48,7 +49,7 @@ $ CXX=/opt/rocm/bin/hipcc cmake -DCMAKE_PREFIX_PATH=/opt/rocm/ -DCMAKE_INSTALL_P
 ```
 Note: ensure rocm-cmake is installed, `apt install rocm-cmake`.
 
-#### To build the RCCL package and install package :
+### To build the RCCL package and install package :
 
 Assuming you have already cloned this repository and built the library as shown in the previous section:
 
@@ -61,6 +62,7 @@ $ sudo dpkg -i *.deb
 RCCL package install requires sudo/root access because it creates a directory called "rccl" under /opt/rocm/. This is an optional step and RCCL can be used directly by including the path containing librccl.so.
 
 ## Enabling peer-to-peer transport
+
 In order to enable peer-to-peer access on machines with PCIe-connected GPUs, the HSA environment variable HSA_FORCE_FINE_GRAIN_PCIE=1 is required to be set, on top of requiring GPUs that support peer-to-peer access and proper large BAR addressing support.
 
 ## Tests
@@ -97,7 +99,19 @@ To manually analyze NPKit dump results, please leverage [npkit_trace_generator.p
 
 ## Library and API Documentation
 
-Please refer to the [Library documentation](https://rccl.readthedocs.io/) for current documentation.
+Please refer to the [RCCL Documentation Site](https://rocm.docs.amd.com/projects/rccl/en/latest/) for current documentation.
+
+### How to build documentation
+
+Run the steps below to build documentation locally.
+
+```
+cd docs
+
+pip3 install -r sphinx/requirements.txt
+
+python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
+```
 
 ## Copyright
 

diff --git a/custom.properties b/custom.properties
diff --git a/docs/allapi.rst b/docs/allapi.rst
@@ -0,0 +1,7 @@
+=======
+All API
+=======
+
+.. doxygenindex::
+
+
diff --git a/docs/source/api.rst → docs/api.rst b/docs/source/api.rst → docs/api.rst
diff --git a/docs/source/attributions.rst → docs/attributions.rst b/docs/source/attributions.rst → docs/attributions.rst
@@ -40,8 +40,4 @@ under subcontract 7078610 with Lawrence Berkeley National Laboratory.
 
 This code also includes files from the NVIDIA Tools Extension SDK project.
 
-For more information and license details, see
-
- https://github.com/NVIDIA/NVTX
-
-
+For more information and license details, see [https://github.com/NVIDIA/NVTX](https://github.com/NVIDIA/NVTX)
diff --git a/docs/classification-map.xml b/docs/classification-map.xml
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import subprocess
+
+from rocm_docs import ROCmDocs
+
+
+name = "RCCL"
+get_major = r'sed -n -e "s/^NCCL_MAJOR.*\([0-9]\+\).*/\1/p" ../makefiles/version.mk'
+get_minor = r'sed -n -e "s/^NCCL_MINOR.*\([0-9]\{2,\}\).*/\1/p" ../makefiles/version.mk'
+get_patch = r'sed -n -e "s/^NCCL_PATCH.*\([0-9]\+\).*/\1/p" ../makefiles/version.mk'
+major = subprocess.getoutput(get_major)
+minor = subprocess.getoutput(get_minor)
+patch = subprocess.getoutput(get_patch)
+
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(f"{name} {major}.{minor}.{patch} Documentation")
+docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/docBin/xml")
+docs_core.setup()
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)
diff --git a/docs/Doxyfile → docs/doxygen/Doxyfile b/docs/Doxyfile → docs/doxygen/Doxyfile
@@ -52,7 +52,7 @@ PROJECT_BRIEF          = "prototype interfaces compatible with ROCm platform and
 # 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
@@ -778,7 +778,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = nccl.h
+INPUT                  = ../../tools/topo_expl/include/nccl.h
 
 # 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
@@ -960,7 +960,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ../README.md
+# USE_MDFILE_AS_MAINPAGE = ../README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing