Standardize hipBLASLt documentation builds (ROCm#64)

* standardize docs * fix typo
are-we-gfx1100-yet · Mar 22, 2023 · daf698f · daf698f
1 parent 54b7d0b
commit daf698f
Show file tree

Hide file tree

Showing 24 changed files with 348 additions and 299 deletions.
diff --git a/.gitignore b/.gitignore
@@ -35,12 +35,14 @@ tags
 # Editors
 .vscode
 
-# build-in-source directory
-build
-
-# doc directory
-docBin
-_build
+# build-in-source directory and documentation artifacts
+build/
+_build/
+_images/
+_static/
+_templates/
+_toc.yml
+docBin/
 
 # matrices
 *.csr

diff --git a/.readthedocs.yaml b/.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/README.md b/README.md
@@ -21,7 +21,16 @@ Here are data type supported list:
 | bf16  | bf16  | bf16  | bf16  | fp32  |
 
 ## Documentation 
-Refer to doc folder 
+
+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
+```
 
 ## Requirements
 * Git

diff --git a/docs/Doxyfile → docs/.doxygen/Doxyfile b/docs/Doxyfile → docs/.doxygen/Doxyfile
@@ -51,7 +51,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           = ./source/rocm_logo.png
+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
@@ -775,7 +775,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../library/include
+INPUT                  = ../../library/include
 
 # 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

diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in
@@ -0,0 +1,12 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+root: index
+subtrees:
+  - numbered: False
+    entries:
+    - file: designdoc
+    - file: install
+    - file: deprecation
+    - file: orga
+    - file: functions
+
diff --git a/docs/.sphinx/requirements.in b/docs/.sphinx/requirements.in
@@ -0,0 +1 @@
+git+https://github.com/RadeonOpenCompute/rocm-docs-core.git
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
@@ -0,0 +1,278 @@
+#
+# 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
+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
+    # via rocm-docs-core
+certifi==2022.12.7
+    # via requests
+cffi==1.15.1
+    # via 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
+deprecated==1.2.13
+    # via pygithub
+docutils==0.16
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   rocm-docs-core
+    #   sphinx
+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
+    #   jupyter-client
+    #   myst-nb
+importlib-resources==5.10.4
+    # via
+    #   jsonschema
+    #   rocm-docs-core
+ipykernel==6.21.3
+    # via myst-nb
+ipython==8.11.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==8.0.3
+    # via
+    #   ipykernel
+    #   nbclient
+jupyter-core==5.3.0
+    # via
+    #   ipykernel
+    #   jupyter-client
+    #   nbformat
+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
+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
+    # 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
+pkgutil-resolve-name==1.3.10
+    # via jsonschema
+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
+pycparser==2.21
+    # via cffi
+pydata-sphinx-theme==0.13.1
+    # via sphinx-book-theme
+pygithub==1.57
+    # via rocm-docs-core
+pygments==2.14.0
+    # via
+    #   accessible-pygments
+    #   ipython
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt==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==2022.7.1
+    # via babel
+pyyaml==6.0
+    # via
+    #   jupyter-cache
+    #   myst-nb
+    #   myst-parser
+    #   sphinx-external-toc
+pyzmq==25.0.1
+    # via
+    #   ipykernel
+    #   jupyter-client
+requests==2.28.2
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core @ git+https://github.com/RadeonOpenCompute/rocm-docs-core.git
+    # 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.4
+    # 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.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
+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
+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
+    #   importlib-resources
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools
diff --git a/docs/source/clients.rst → docs/clients.rst b/docs/source/clients.rst → docs/clients.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,14 @@
+# 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
+
+from rocm_docs import ROCmDocs
+
+docs_core = ROCmDocs("hipBLASLt Documentation")
+docs_core.run_doxygen()
+docs_core.setup()
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)
diff --git a/docs/source/deprecation.rst → docs/deprecation.rst b/docs/source/deprecation.rst → docs/deprecation.rst
@@ -5,6 +5,5 @@ Deprecations by version
 Announced in hipBLASLt 0.0.1
 ****************************
 
-Initial verison of hipBLASLt
+Initial version of hipBLASLt
 ===========================================================
-
diff --git a/docs/source/designdoc.rst → docs/designdoc.rst b/docs/source/designdoc.rst → docs/designdoc.rst
@@ -8,5 +8,4 @@ Design Documentation
    :maxdepth: 3
    :caption: Contents:
 
-   disclaimer
    clients
diff --git a/docs/source/functions.rst → docs/functions.rst b/docs/source/functions.rst → docs/functions.rst
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		git+https://github.com/RadeonOpenCompute/rocm-docs-core.git