From 4bb12a1bd8ff3f10fd2506fc680fd18f4d60207e Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Thu, 18 May 2023 11:08:38 -0600 Subject: [PATCH] Documentation Updates (#710) * update documentation dependencies add version number to docs rename doc config directories enable more doc formats on rtd add license section in docs [ROCm/composable_kernel commit: 3cff34042385ee7dadf9252fc667b1285d4cee38] --- .github/dependabot.yml | 2 +- .gitignore | 2 +- .readthedocs.yaml | 4 +- README.md | 16 +- docs/.sphinx/_toc.yml.in | 1 - docs/conf.py | 15 +- docs/{.doxygen => doxygen}/Doxyfile | 0 docs/license.rst | 6 + docs/sphinx/_toc.yml.in | 10 ++ docs/{.sphinx => sphinx}/requirements.in | 2 +- docs/{.sphinx => sphinx}/requirements.txt | 171 ++++------------------ 11 files changed, 79 insertions(+), 150 deletions(-) delete mode 100644 docs/.sphinx/_toc.yml.in rename docs/{.doxygen => doxygen}/Doxyfile (100%) create mode 100644 docs/license.rst create mode 100644 docs/sphinx/_toc.yml.in rename docs/{.sphinx => sphinx}/requirements.in (54%) rename docs/{.sphinx => sphinx}/requirements.txt (51%) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9cdf2d670c..276690bd4f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -6,7 +6,7 @@ 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" diff --git a/.gitignore b/.gitignore index 362fb9e2ef..7af066c82d 100644 --- a/.gitignore +++ b/.gitignore @@ -49,10 +49,10 @@ build* install.dir* # documentation artifacts -build/ _build/ _images/ _static/ _templates/ _toc.yml docBin/ +_doxygen/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index b739536837..5f50df2525 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,8 +11,8 @@ build: sphinx: configuration: docs/conf.py -formats: [htmlzip] +formats: [htmlzip, pdf, epub] python: install: - - requirements: docs/.sphinx/requirements.txt + - requirements: docs/sphinx/requirements.txt diff --git a/README.md b/README.md index 04199f11bf..a45f61a37d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Composable Kernel ## Methodology + Composable Kernel (CK) library aims to provide a programming model for writing performance critical kernels for machine learning workloads across multiple architectures including GPUs, CPUs, etc, through general purpose kernel languages, like HIP C++. CK utilizes two concepts to achieve performance portability and code maintainability: @@ -10,6 +11,7 @@ CK utilizes two concepts to achieve performance portability and code maintainabi ![ALT](/docs/data/ck_component.png "CK Components") ## Code Structure + Current CK library are structured into 4 layers: * "Templated Tile Operators" layer * "Templated Kernel and Invoker" layer @@ -24,30 +26,35 @@ 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 ``` ## Contributors + The list of developers and contributors is here: [Contributors](/CONTRIBUTORS.md) ## Citation + If you use CK, please use following citations: * CK paper will be freely available on arXiv soon: [Realizing Tensor Operators Using Coordinate Transformations and Tile Based Programming](???) * [CITATION.cff](/CITATION.cff) ## License + CK is released under the MIT license. [License File](/LICENSE) # Build CK ## Build docker image + ```bash DOCKER_BUILDKIT=1 docker build -t ck:latest -f Dockerfile . ``` ## Launch docker + ```bash docker run \ -it \ @@ -60,10 +67,12 @@ ck:latest \ ``` ## Build CK + ```bash mkdir build && cd build # Need to specify target ID, example below is for gfx908 and gfx90a + cmake \ -D CMAKE_PREFIX_PATH=/opt/rocm \ -D CMAKE_CXX_COMPILER=/opt/rocm/bin/hipcc \ @@ -74,6 +83,7 @@ cmake ``` ### Build examples and tests + ```bash make -j examples tests make test @@ -83,21 +93,25 @@ Instructions for running each individual examples are under [example](/example) ## Build ckProfiler + ```bash make -j ckProfiler ``` Instructions for running ckProfiler are under [profiler](/profiler) ## Install CK + ```bash make install ``` ## Using CK as pre-built kernel library + Instructions for using CK as a pre-built kernel library are under [client_example](/client_example) ## Caveat ### Kernel Timing and Verification + CK's own kernel timer will warn up kernel once, and then run it multiple times to get average kernel time. For some kernels that use atomic add, this will cause output buffer to be accumulated multiple times, causing verification failure. diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in deleted file mode 100644 index ff21248873..0000000000 --- a/docs/.sphinx/_toc.yml.in +++ /dev/null @@ -1 +0,0 @@ -root: index diff --git a/docs/conf.py b/docs/conf.py index 3ec81ee9df..0de590da1a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,10 +4,21 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import subprocess + from rocm_docs import ROCmDocs -docs_core = ROCmDocs("Composable Kernel Documentation") -docs_core.run_doxygen() + +name = "Composable Kernel" +get_version = r'sed -n -e "s/^rocm_setup_version(.* \([0-9\.]\{1,\}\).*/\1/p" ../CMakeLists.txt' +version = subprocess.getoutput(get_version) +if len(version) > 0: + name = f"{name} {version}" + +external_toc_path = "./sphinx/_toc.yml" + +docs_core = ROCmDocs(f"{name} Documentation") +docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/docBin/xml") docs_core.setup() mathjax3_config = { 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/license.rst b/docs/license.rst new file mode 100644 index 0000000000..ddb544496e --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,6 @@ +======= +License +======= + +.. include:: ../LICENSE + :literal: diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in new file mode 100644 index 0000000000..83dd1e7b1a --- /dev/null +++ b/docs/sphinx/_toc.yml.in @@ -0,0 +1,10 @@ +# Anywhere {branch} is used, the branch name will be substituted. +# These comments will also be removed. +defaults: + numbered: False + maxdepth: 6 +root: index +subtrees: + - caption: About + entries: + - file: license diff --git a/docs/.sphinx/requirements.in b/docs/sphinx/requirements.in similarity index 54% rename from docs/.sphinx/requirements.in rename to docs/sphinx/requirements.in index 1905de6e6c..4bdf41b959 100644 --- a/docs/.sphinx/requirements.in +++ b/docs/sphinx/requirements.in @@ -1,2 +1,2 @@ -rocm-docs-core==0.2.0 +rocm-docs-core==0.10.3 sphinxcontrib-bibtex==2.5.0 diff --git a/docs/.sphinx/requirements.txt b/docs/sphinx/requirements.txt similarity index 51% rename from docs/.sphinx/requirements.txt rename to docs/sphinx/requirements.txt index d1698b2855..097acba225 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -1,25 +1,17 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.8 # by the following command: # -# pip-compile .sphinx/requirements.in +# pip-compile requirements.in # accessible-pygments==0.0.3 # via pydata-sphinx-theme alabaster==0.7.13 # via sphinx -asttokens==2.2.1 - # via stack-data -attrs==22.2.0 - # via - # jsonschema - # jupyter-cache babel==2.12.1 # via # pydata-sphinx-theme # sphinx -backcall==0.2.0 - # via ipython beautifulsoup4==4.11.2 # via pydata-sphinx-theme breathe==4.34.0 @@ -27,19 +19,15 @@ breathe==4.34.0 certifi==2022.12.7 # via requests cffi==1.15.1 - # via pynacl + # via + # cryptography + # pynacl charset-normalizer==3.1.0 # via requests click==8.1.3 - # via - # jupyter-cache - # sphinx-external-toc -comm==0.1.2 - # via ipykernel -debugpy==1.6.6 - # via ipykernel -decorator==5.1.1 - # via ipython + # via sphinx-external-toc +cryptography==40.0.2 + # via pyjwt deprecated==1.2.13 # via pygithub docutils==0.16 @@ -48,52 +36,26 @@ docutils==0.16 # myst-parser # pybtex-docutils # pydata-sphinx-theme - # rocm-docs-core # sphinx # sphinxcontrib-bibtex -executing==1.2.0 - # via stack-data -fastjsonschema==2.16.3 - # via nbformat gitdb==4.0.10 # via gitpython gitpython==3.1.31 # via rocm-docs-core -greenlet==2.0.2 - # via sqlalchemy idna==3.4 # via requests imagesize==1.4.1 # via sphinx importlib-metadata==6.0.0 # via - # jupyter-cache - # myst-nb -ipykernel==6.21.3 - # via myst-nb -ipython==8.11.0 - # via - # ipykernel - # myst-nb -jedi==0.18.2 - # via ipython + # sphinx + # sphinxcontrib-bibtex +importlib-resources==5.12.0 + # via rocm-docs-core jinja2==3.1.2 # via # myst-parser # sphinx -jsonschema==4.17.3 - # via nbformat -jupyter-cache==0.5.0 - # via myst-nb -jupyter-client==8.0.3 - # via - # ipykernel - # nbclient -jupyter-core==5.3.0 - # via - # ipykernel - # jupyter-client - # nbformat latexcodec==2.0.1 # via pybtex linkify-it-py==1.0.3 @@ -104,54 +66,16 @@ markdown-it-py==2.2.0 # myst-parser markupsafe==2.1.2 # via jinja2 -matplotlib-inline==0.1.6 - # via - # ipykernel - # ipython mdit-py-plugins==0.3.5 # via myst-parser mdurl==0.1.2 # via markdown-it-py -myst-nb==0.17.1 +myst-parser[linkify]==1.0.0 # 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.3 - # via - # jupyter-cache - # myst-nb - # nbclient -nest-asyncio==1.5.6 - # via - # ipykernel - # nbclient packaging==23.0 # 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==3.1.1 - # via jupyter-core -prompt-toolkit==3.0.38 - # via ipython -psutil==5.9.4 - # via ipykernel -ptyprocess==0.7.0 - # via pexpect -pure-eval==0.2.2 - # via stack-data pybtex==0.24.0 # via # pybtex-docutils @@ -160,57 +84,47 @@ pybtex-docutils==1.0.2 # via sphinxcontrib-bibtex pycparser==2.21 # via cffi -pydata-sphinx-theme==0.13.1 - # via sphinx-book-theme -pygithub==1.57 +pydata-sphinx-theme==0.13.3 + # via + # rocm-docs-core + # sphinx-book-theme +pygithub==1.58.2 # via rocm-docs-core pygments==2.14.0 # via # accessible-pygments - # ipython # pydata-sphinx-theme # sphinx -pyjwt==2.6.0 +pyjwt[crypto]==2.6.0 # via pygithub pynacl==1.5.0 # via pygithub -pyrsistent==0.19.3 - # via jsonschema -python-dateutil==2.8.2 - # via jupyter-client +pytz==2023.3 + # via babel pyyaml==6.0 # via - # jupyter-cache - # myst-nb # myst-parser # pybtex # sphinx-external-toc -pyzmq==25.0.1 - # via - # ipykernel - # jupyter-client requests==2.28.2 # via # pygithub # sphinx -rocm-docs-core==0.2.0 - # via -r .sphinx/requirements.in +rocm-docs-core==0.10.3 + # via -r requirements.in six==1.16.0 # via - # asttokens # latexcodec # pybtex - # python-dateutil smmap==5.0.0 # via gitdb snowballstemmer==2.2.0 # via sphinx soupsieve==2.4 # via beautifulsoup4 -sphinx==4.3.1 +sphinx==5.3.0 # via # breathe - # myst-nb # myst-parser # pydata-sphinx-theme # rocm-docs-core @@ -220,7 +134,7 @@ sphinx==4.3.1 # sphinx-external-toc # sphinx-notfound-page # sphinxcontrib-bibtex -sphinx-book-theme==1.0.0rc2 +sphinx-book-theme==1.0.1 # via rocm-docs-core sphinx-copybutton==0.5.1 # via rocm-docs-core @@ -233,7 +147,7 @@ sphinx-notfound-page==0.8.3 sphinxcontrib-applehelp==1.0.4 # via sphinx sphinxcontrib-bibtex==2.5.0 - # via -r .sphinx/requirements.in + # via -r requirements.in sphinxcontrib-devhelp==1.0.2 # via sphinx sphinxcontrib-htmlhelp==2.0.1 @@ -244,40 +158,15 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx -sqlalchemy==1.4.46 - # 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.9.0 - # via - # comm - # ipykernel - # ipython - # jupyter-client - # jupyter-core - # matplotlib-inline - # nbclient - # nbformat typing-extensions==4.5.0 - # via - # myst-nb - # myst-parser + # via pydata-sphinx-theme uc-micro-py==1.0.1 # via linkify-it-py urllib3==1.26.15 # via requests -wcwidth==0.2.6 - # via prompt-toolkit wrapt==1.15.0 # via deprecated zipp==3.15.0 - # via importlib-metadata - -# The following packages are considered to be unsafe in a requirements file: -# setuptools + # via + # importlib-metadata + # importlib-resources