diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9cdf2d670..1c3fa17b1 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -6,7 +6,12 @@ version: 2 updates: - package-ecosystem: "pip" # See documentation for possible values - directory: "/docs/.sphinx" # Location of package manifests + 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 index 402fdcc8e..919c9dffb 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ _static/ _templates/ _toc.yml docBin/ +_doxygen/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 43a0890c9..5f50df252 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -3,12 +3,16 @@ version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.8" + sphinx: configuration: docs/conf.py -formats: [htmlzip] +formats: [htmlzip, pdf, epub] python: - version: "3.8" install: - - requirements: docs/.sphinx/requirements.txt + - requirements: docs/sphinx/requirements.txt diff --git a/README.md b/README.md index 379df2d27..f47f2d596 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ The root of this repository has a helper script 'install.sh' to build and instal * `./install.sh --npkit-enable` -- enable compilation of npkit profiler framework with all options ## Manual build + ### To build the library : ```shell @@ -61,18 +62,8 @@ $ 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. -### How to build documentation -Please follow the instructions below to build the documentation. -```bash -cd docs - -pip3 install -r .sphinx/requirements.txt - -python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html -``` - - ## 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 @@ -109,7 +100,7 @@ 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 @@ -118,7 +109,7 @@ Run the steps below to build documentation locally. ``` cd docs -pip3 install -r .sphinx/requirements.txt +pip3 install -r sphinx/requirements.txt python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html ``` diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in deleted file mode 100644 index 9d09f6484..000000000 --- a/docs/.sphinx/requirements.in +++ /dev/null @@ -1 +0,0 @@ -rocm-docs-core==0.5.0 diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt deleted file mode 100644 index 498ab97c9..000000000 --- a/docs/.sphinx/requirements.txt +++ /dev/null @@ -1,273 +0,0 @@ -# -# This file is autogenerated by pip-compile with Python 3.10 -# by the following command: -# -# pip-compile .sphinx/requirements.in -# -accessible-pygments==0.0.3 - # via pydata-sphinx-theme -alabaster==0.7.12 - # via sphinx -asttokens==2.2.0 - # via stack-data -attrs==22.1.0 - # via - # jsonschema - # jupyter-cache -babel==2.10.3 - # via - # pydata-sphinx-theme - # sphinx -backcall==0.2.0 - # via ipython -beautifulsoup4==4.11.1 - # via pydata-sphinx-theme -breathe==4.34.0 - # via rocm-docs-core -certifi==2022.6.15 - # via requests -cffi==1.15.1 - # via pynacl -charset-normalizer==2.1.0 - # via requests -click==8.1.3 - # via - # jupyter-cache - # sphinx-external-toc -debugpy==1.6.4 - # via ipykernel -decorator==5.1.1 - # via ipython -deprecated==1.2.13 - # via pygithub -docutils==0.16 - # via - # breathe - # myst-parser - # pydata-sphinx-theme - # rocm-docs-core - # sphinx -entrypoints==0.4 - # via jupyter-client -executing==1.2.0 - # via stack-data -fastjsonschema==2.16.2 - # via nbformat -gitdb==4.0.10 - # via gitpython -gitpython==3.1.31 - # via rocm-docs-core -greenlet==2.0.1 - # via sqlalchemy -idna==3.3 - # via requests -imagesize==1.4.1 - # via sphinx -importlib-metadata==5.1.0 - # via - # jupyter-cache - # myst-nb -ipykernel==6.17.1 - # via myst-nb -ipython==8.7.0 - # via - # ipykernel - # myst-nb -jedi==0.18.2 - # via ipython -jinja2==3.1.2 - # via - # myst-parser - # sphinx -jsonschema==4.17.3 - # via nbformat -jupyter-cache==0.5.0 - # via myst-nb -jupyter-client==7.4.7 - # via - # ipykernel - # nbclient -jupyter-core==5.1.0 - # via - # jupyter-client - # nbformat -linkify-it-py==1.0.3 - # via myst-parser -markdown-it-py==2.1.0 - # via - # mdit-py-plugins - # myst-parser -markupsafe==2.1.1 - # via jinja2 -matplotlib-inline==0.1.6 - # via - # ipykernel - # ipython -mdit-py-plugins==0.3.1 - # via myst-parser -mdurl==0.1.2 - # via markdown-it-py -myst-nb==0.17.1 - # via rocm-docs-core -myst-parser[linkify]==0.18.1 - # via - # myst-nb - # rocm-docs-core -nbclient==0.5.13 - # via - # jupyter-cache - # myst-nb -nbformat==5.7.0 - # via - # jupyter-cache - # myst-nb - # nbclient -nest-asyncio==1.5.6 - # via - # ipykernel - # jupyter-client - # nbclient -packaging==21.3 - # via - # ipykernel - # pydata-sphinx-theme - # sphinx -parso==0.8.3 - # via jedi -pexpect==4.8.0 - # via ipython -pickleshare==0.7.5 - # via ipython -platformdirs==2.5.4 - # via jupyter-core -prompt-toolkit==3.0.33 - # via ipython -psutil==5.9.4 - # via ipykernel -ptyprocess==0.7.0 - # via pexpect -pure-eval==0.2.2 - # via stack-data -pycparser==2.21 - # via cffi -pydata-sphinx-theme==0.13.3 - # via - # rocm-docs-core - # sphinx-book-theme -pygithub==1.57 - # via rocm-docs-core -pygments==2.12.0 - # via - # accessible-pygments - # ipython - # pydata-sphinx-theme - # sphinx -pyjwt==2.6.0 - # via pygithub -pynacl==1.5.0 - # via pygithub -pyparsing==3.0.9 - # via packaging -pyrsistent==0.19.2 - # via jsonschema -python-dateutil==2.8.2 - # via jupyter-client -pytz==2022.1 - # via babel -pyyaml==6.0 - # via - # jupyter-cache - # myst-nb - # myst-parser - # sphinx-external-toc -pyzmq==24.0.1 - # via - # ipykernel - # jupyter-client -requests==2.28.1 - # via - # pygithub - # sphinx -rocm-docs-core==0.5.0 - # via -r requirements.in -six==1.16.0 - # via - # asttokens - # python-dateutil -smmap==5.0.0 - # via gitdb -snowballstemmer==2.2.0 - # via sphinx -soupsieve==2.3.2.post1 - # via beautifulsoup4 -sphinx==4.3.1 - # via - # breathe - # myst-nb - # 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.0rc2 - # via rocm-docs-core -sphinx-copybutton==0.5.1 - # via rocm-docs-core -sphinx-design==0.3.0 - # 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.2 - # via sphinx -sphinxcontrib-devhelp==1.0.2 - # via sphinx -sphinxcontrib-htmlhelp==2.0.0 - # via sphinx -sphinxcontrib-jsmath==1.0.1 - # via sphinx -sphinxcontrib-qthelp==1.0.3 - # via sphinx -sphinxcontrib-serializinghtml==1.1.5 - # via sphinx -sqlalchemy==1.4.44 - # via jupyter-cache -stack-data==0.6.2 - # via ipython -tabulate==0.9.0 - # via jupyter-cache -tornado==6.2 - # via - # ipykernel - # jupyter-client -traitlets==5.6.0 - # via - # ipykernel - # ipython - # jupyter-client - # jupyter-core - # matplotlib-inline - # nbclient - # nbformat -typing-extensions==4.4.0 - # via - # myst-nb - # myst-parser - # pydata-sphinx-theme -uc-micro-py==1.0.1 - # via linkify-it-py -urllib3==1.26.11 - # via requests -wcwidth==0.2.5 - # via prompt-toolkit -wrapt==1.15.0 - # via deprecated -zipp==3.11.0 - # via importlib-metadata - -# The following packages are considered to be unsafe in a requirements file: -# setuptools diff --git a/docs/attributions.rst b/docs/attributions.rst index 9eb3e4120..36beccd6c 100644 --- a/docs/attributions.rst +++ b/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/conf.py b/docs/conf.py index bb4550a2c..74773b478 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,10 +4,23 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import subprocess + from rocm_docs import ROCmDocs -docs_core = ROCmDocs("RCCL Documentation") -docs_core.run_doxygen() + +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: diff --git a/docs/.doxygen/Doxyfile b/docs/doxygen/Doxyfile similarity index 100% rename from docs/.doxygen/Doxyfile rename to docs/doxygen/Doxyfile diff --git a/docs/index.rst b/docs/index.rst index 8da1bc899..aacc95593 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,11 @@ -****************** -RCCL documentation -****************** +**** +RCCL +**** -The ROCm Collective Communication Library (RCCL) is a stand-alone library which provides multi-GPU and multi-node collective communication primitives optimized for AMD GPUs. RCCL (pronounced “Rickel”) implements routines such as all-reduce, all-gather, reduce, broadcast, reduce-scatter, gather, scatter, all-to-allv, and all-to-all as well as direct point-to-point (GPU-to-GPU) send and receive operations. The provided collective communication routines are implemented using Ring and Tree algorithms. They are optimized to achieve high bandwidth and low latency by leveraging topology awareness, high-speed interconnects, RDMA based collectives. RCCL utilizes PCIe and xGMI high-speed interconnects for intra-node communication as well as InfiniBand, RoCE, and TCP/IP for inter-node communication.  -RCCL supports an arbitrary number of GPUs installed in a single-node or multi-node platform. It can be easily integrated into either single- or multi-process (e.g., MPI) applications. +The ROCm Collective Communication Library (RCCL) is a stand-alone library which provides multi-GPU and multi-node collective communication primitives optimized for AMD GPUs. +RCCL (pronounced “Rickel”) implements routines such as all-reduce, all-gather, reduce, broadcast, reduce-scatter, gather, scatter, all-to-allv, and all-to-all as well as direct point-to-point (GPU-to-GPU) send and receive operations. +The provided collective communication routines are implemented using Ring and Tree algorithms. They are optimized to achieve high bandwidth and low latency by leveraging topology awareness, high-speed interconnects, RDMA based collectives. RCCL utilizes PCIe and xGMI high-speed interconnects for intra-node communication as well as InfiniBand, RoCE, and TCP/IP for inter-node communication. +RCCL supports an arbitrary number of GPUs installed in a single-node or multi-node platform. It can be easily integrated into either single- or multi-process (e.g., MPI) applications. diff --git a/docs/.sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in similarity index 100% rename from docs/.sphinx/_toc.yml.in rename to docs/sphinx/_toc.yml.in diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 000000000..7f2c40a8e --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core==0.13.4 diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt new file mode 100644 index 000000000..210c72dc4 --- /dev/null +++ b/docs/sphinx/requirements.txt @@ -0,0 +1,155 @@ +# +# 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 +importlib-metadata==6.6.0 + # via sphinx +importlib-resources==5.12.0 + # via rocm-docs-core +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 +pytz==2023.3 + # via babel +pyyaml==6.0 + # via + # myst-parser + # rocm-docs-core + # sphinx-external-toc +requests==2.28.2 + # via + # pygithub + # sphinx +rocm-docs-core==0.13.4 + # 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 +zipp==3.15.0 + # via + # importlib-metadata + # importlib-resources