From 8fdc4795fd63b3e2a79fee42d3ea808bd86c632f Mon Sep 17 00:00:00 2001 From: Saad Rahim <44449863+saadrahim@users.noreply.github.com> Date: Mon, 13 Mar 2023 11:00:57 -0600 Subject: [PATCH] Standard template implementation (#703) [ROCm/rccl commit: 6e48e518d944a6e6dc80176c42d5e6839b86c2c8] --- projects/rccl/.readthedocs.yaml | 14 + projects/rccl/README.md | 15 +- projects/rccl/custom.properties | 3 - projects/rccl/docs/{ => .doxygen}/Doxyfile | 6 +- projects/rccl/docs/.sphinx/_toc.yml.in | 8 + projects/rccl/docs/.sphinx/requirements.in | 1 + projects/rccl/docs/.sphinx/requirements.txt | 275 ++++++++++++++++++ projects/rccl/docs/allapi.rst | 7 + projects/rccl/docs/{source => }/api.rst | 0 .../rccl/docs/{source => }/attributions.rst | 0 projects/rccl/docs/classification-map.xml | 189 ------------ projects/rccl/docs/conf.py | 14 + .../docs/{source/library.rst => index.rst} | 16 +- projects/rccl/docs/rocm.jpg | Bin 6761 -> 0 bytes projects/rccl/docs/run_doc.sh | 15 - projects/rccl/docs/run_doxygen.sh | 17 -- projects/rccl/docs/source/Makefile | 20 -- projects/rccl/docs/source/allapi.rst | 11 - projects/rccl/docs/source/conf.py | 182 ------------ projects/rccl/docs/source/index.rst | 22 -- projects/rccl/docs/source/requirements.txt | 3 - 21 files changed, 340 insertions(+), 478 deletions(-) create mode 100644 projects/rccl/.readthedocs.yaml delete mode 100644 projects/rccl/custom.properties rename projects/rccl/docs/{ => .doxygen}/Doxyfile (99%) create mode 100644 projects/rccl/docs/.sphinx/_toc.yml.in create mode 100644 projects/rccl/docs/.sphinx/requirements.in create mode 100644 projects/rccl/docs/.sphinx/requirements.txt create mode 100644 projects/rccl/docs/allapi.rst rename projects/rccl/docs/{source => }/api.rst (100%) rename projects/rccl/docs/{source => }/attributions.rst (100%) delete mode 100644 projects/rccl/docs/classification-map.xml create mode 100644 projects/rccl/docs/conf.py rename projects/rccl/docs/{source/library.rst => index.rst} (90%) delete mode 100644 projects/rccl/docs/rocm.jpg delete mode 100755 projects/rccl/docs/run_doc.sh delete mode 100755 projects/rccl/docs/run_doxygen.sh delete mode 100644 projects/rccl/docs/source/Makefile delete mode 100644 projects/rccl/docs/source/allapi.rst delete mode 100644 projects/rccl/docs/source/conf.py delete mode 100644 projects/rccl/docs/source/index.rst delete mode 100644 projects/rccl/docs/source/requirements.txt diff --git a/projects/rccl/.readthedocs.yaml b/projects/rccl/.readthedocs.yaml new file mode 100644 index 0000000000..43a0890c96 --- /dev/null +++ b/projects/rccl/.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/projects/rccl/README.md b/projects/rccl/README.md index 42bfa7ce8c..1b8db6a456 100644 --- a/projects/rccl/README.md +++ b/projects/rccl/README.md @@ -32,7 +32,7 @@ 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 +48,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: @@ -60,6 +60,17 @@ $ 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. diff --git a/projects/rccl/custom.properties b/projects/rccl/custom.properties deleted file mode 100644 index 45e5972fc3..0000000000 --- a/projects/rccl/custom.properties +++ /dev/null @@ -1,3 +0,0 @@ -booktitle=RCCL API Guide -spreadsheet.xml=docs/classification-map.xml -document.locale=enus \ No newline at end of file diff --git a/projects/rccl/docs/Doxyfile b/projects/rccl/docs/.doxygen/Doxyfile similarity index 99% rename from projects/rccl/docs/Doxyfile rename to projects/rccl/docs/.doxygen/Doxyfile index 8ee1e20c51..9e5f7f1f8b 100644 --- a/projects/rccl/docs/Doxyfile +++ b/projects/rccl/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 diff --git a/projects/rccl/docs/.sphinx/_toc.yml.in b/projects/rccl/docs/.sphinx/_toc.yml.in new file mode 100644 index 0000000000..731cc40627 --- /dev/null +++ b/projects/rccl/docs/.sphinx/_toc.yml.in @@ -0,0 +1,8 @@ +root: index +subtrees: +- entries: + - file: api + - file: allapi + - file: attributions + + diff --git a/projects/rccl/docs/.sphinx/requirements.in b/projects/rccl/docs/.sphinx/requirements.in new file mode 100644 index 0000000000..c5f387dbcc --- /dev/null +++ b/projects/rccl/docs/.sphinx/requirements.in @@ -0,0 +1 @@ +git+https://github.com/RadeonOpenCompute/rocm-docs-core.git \ No newline at end of file diff --git a/projects/rccl/docs/.sphinx/requirements.txt b/projects/rccl/docs/.sphinx/requirements.txt new file mode 100644 index 0000000000..9abd19aca9 --- /dev/null +++ b/projects/rccl/docs/.sphinx/requirements.txt @@ -0,0 +1,275 @@ +# +# This file is autogenerated by pip-compile with Python 3.8 +# by the following command: +# +# pip-compile docs/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 +importlib-resources==5.10.4 + # via + # jsonschema + # rocm-docs-core +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 +pkgutil-resolve-name==1.3.10 + # via jsonschema +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.1 + # via 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 @ git+https://github.com/RadeonOpenCompute/rocm-docs-core.git + # via -r docs/sphinx/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-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 +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 +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 + # importlib-resources + +# The following packages are considered to be unsafe in a requirements file: +# setuptools diff --git a/projects/rccl/docs/allapi.rst b/projects/rccl/docs/allapi.rst new file mode 100644 index 0000000000..ca48fa77c6 --- /dev/null +++ b/projects/rccl/docs/allapi.rst @@ -0,0 +1,7 @@ +======= +All API +======= + +.. doxygenindex:: + + diff --git a/projects/rccl/docs/source/api.rst b/projects/rccl/docs/api.rst similarity index 100% rename from projects/rccl/docs/source/api.rst rename to projects/rccl/docs/api.rst diff --git a/projects/rccl/docs/source/attributions.rst b/projects/rccl/docs/attributions.rst similarity index 100% rename from projects/rccl/docs/source/attributions.rst rename to projects/rccl/docs/attributions.rst diff --git a/projects/rccl/docs/classification-map.xml b/projects/rccl/docs/classification-map.xml deleted file mode 100644 index b636fd38b4..0000000000 --- a/projects/rccl/docs/classification-map.xml +++ /dev/null @@ -1,189 +0,0 @@ - - - - - Kanika Yadav (external) - Microsoft Office User - 2020-09-25T06:54:04Z - 2021-12-22T19:07:50Z - 16.00 - - - true - 2021-02-23T09:13:03Z - Standard - 90c2fedb-0da6-4717-8531-d16a1b9930f4 - 45597f60-6e37-4be7-acfb-4c9e23b261ea - - 0 - true - 2022-01-14T16:33:39Z - Privileged - AMD Official Use Only-AIP 2.0 - 3dd8961f-e488-4e60-8e11-a82d994e183d - 3ab6c0f7-c658-4f6f-bd9d-6ef921551ff7 - 1 - - - - - - 14235 - 32767 - 32767 - 32767 - False - False - - - - - - - - - - - - - - - - - Filename - Title - Categories - Version - Doc Type - - - MAP - rocm;hip-sdk;hip;gpu;amd;rccl; - 4-5 - - - apply-ALL - - - default - - - RCCL API Guide - - reference - - - - - - - - - - - - - - - - - - - -
- - -
-