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

.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"

.gitignore

@@ -49,10 +49,10 @@ build*
 install.dir*
 
 # documentation artifacts
-build/
 _build/
 _images/
 _static/
 _templates/
 _toc.yml
 docBin/
+_doxygen/

.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

README.md

 # 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.

docs/.sphinx/_toc.yml.in

-root: index

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 = {

docs/license.rst

+=======
+License
+=======
+
+.. include:: ../LICENSE
+   :literal:

docs/sphinx/_toc.yml.in

+# 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

docs/.sphinx/requirements.in → docs/sphinx/requirements.in

-rocm-docs-core==0.2.0
+rocm-docs-core==0.10.3
 sphinxcontrib-bibtex==2.5.0

docs/.sphinx/requirements.txt → docs/sphinx/requirements.txt

 #
-# 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