Documentation update for Read the Docs

Standardize hipBLAS documentation builds to use the rocm-docs-core template (#566) * Changing Documentation Template * Changing Documentation Template * hipBLAS documentation refactored for pitchfork * Remove old rocm logo * Reorganize sections to match swab-documentation for reference libraries https://github.com/RadeonOpenCompute/swab-documentation/blob/main/docs/sphinx/templates/references/reference_library.md * Moving files around * Renaming conf.py to sphix_conf.py * Recompile requirements.txt * Fix typo * Renaming back * Update requirements * Point requirements to rocm-docs-core * updating yml * final move for conf.py * Update toc file entries * Renaming folders * Updating rtd yaml with new folder structure * Rename sphinx and doxygen folders prepend . to indicate config folders * Remove extra header * Build html only pdf etc not used * Add section on how to build documentation locally --------- Co-authored-by: Sergey Kostrov <[email protected]> Co-authored-by: Saad Rahim <[email protected]> Update requirements.txt (#574) * update requirements remove unused .gitignore * fix typo in functions docs page * brain float 16 * remove disclaimer Add dependabot config and pin rocm-docs-core (#586) Update dependabot config (#589) Co-authored-by: samjwu <[email protected]> rocm-docs-core==0.13.4 remove old docs action (#598)
ROCm · Jun 14, 2023 · 1322626 · 1322626
1 parent cb9ab00
commit 1322626
Show file tree

Hide file tree

Showing 30 changed files with 228 additions and 340 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/docs/.sphinx" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
diff --git a/.gitignore b/.gitignore
@@ -38,3 +38,13 @@ build*
 .\#*
 \#*\#
 *~
+
+# documentation artifacts
+build/
+_build/
+_images/
+_static/
+_templates/
+_toc.yml
+docBin/
+_doxygen/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -4,11 +4,11 @@
 version: 2
 
 sphinx:
-   configuration: docs/source/conf.py
+   configuration: docs/conf.py
 
-formats: all
+formats: [htmlzip]
 
 python:
-   version: "3.7"
+   version: "3.8"
    install:
-   - requirements: docs/source/requirements.txt
+   - requirements: docs/.sphinx/requirements.txt
diff --git a/README.md b/README.md
@@ -8,6 +8,18 @@ For a detailed description of the **hipBLAS** library, its implemented routines,
 
 hipBLAS requires either **rocBLAS** + **rocSOLVER** or **cuBLAS** APIs for BLAS implementation. For more information dependent **roc*** libraries see [rocBLAS documentation](https://rocblas.readthedocs.io/en/latest/), and [rocSolver documentation](https://rocsolver.readthedocs.io/en/latest/).
 
+### How to build documentation
+
+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
+```
+
 ## Quickstart build
 
 To download the **hipBLAS** source code, use the below command to clone the repository

diff --git a/docs/Doxyfile → docs/.doxygen/Doxyfile b/docs/Doxyfile → docs/.doxygen/Doxyfile
@@ -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/.doxygen/README.md b/docs/.doxygen/README.md
@@ -0,0 +1,4 @@
+# Doxygen Instructions
+
+Please run the following command to build the doxygen based documentation.
+```doxygen Doxyfile```
diff --git a/docs/.gitignore b/docs/.gitignore
diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in
@@ -0,0 +1,13 @@
+# 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: orga
+    - file: api
+    - file: functions
+    - file: deprecation
+    - file: contributing
diff --git a/docs/.sphinx/requirements.in 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
@@ -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.4
+    # via pydata-sphinx-theme
+alabaster==0.7.13
+    # via sphinx
+babel==2.12.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.12.2
+    # via pydata-sphinx-theme
+breathe==4.35.0
+    # via rocm-docs-core
+certifi==2023.5.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==41.0.1
+    # via pyjwt
+deprecated==1.2.14
+    # via pygithub
+docutils==0.19
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+fastjsonschema==2.17.1
+    # 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.3
+    # 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.1
+    # 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.2
+    # via rocm-docs-core
+pygments==2.15.1
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt[crypto]==2.7.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.31.0
+    # 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.1
+    # 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.2
+    # 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.6.3
+    # via pydata-sphinx-theme
+uc-micro-py==1.0.2
+    # via linkify-it-py
+urllib3==2.0.3
+    # via requests
+wrapt==1.15.0
+    # via deprecated
+zipp==3.15.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources
diff --git a/docs/source/api.rst → docs/api.rst b/docs/source/api.rst → docs/api.rst
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("hipBLAS 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/contributing.rst → docs/contributing.rst b/docs/source/contributing.rst → docs/contributing.rst
diff --git a/docs/source/deprecation.rst → docs/deprecation.rst b/docs/source/deprecation.rst → docs/deprecation.rst
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
@@ -20,7 +20,7 @@ Notations
 hipBLAS function uses the following notations to denote precisions,
 
 - h  = half
-- bf = 16 bit brian floating point
+- bf = 16 bit brain floating point
 - s  = single
 - d  = double
 - c  = single complex

diff --git a/docs/source/intro.rst → docs/index.rst b/docs/source/intro.rst → docs/index.rst
@@ -6,7 +6,7 @@ AMD **ROCm** has two classification of libraries,
 - **roc**\* : AMD GPU Libraries, written in `HIP <https://docs.amd.com/bundle/AMD_HIP_Programming_Guide/page/Introduction.html>`_.
 - **hip**\* : AMD CPU library that is a thin interface to either AMD **roc*** or Nvidia **cu*** libraries.
 
-Users targetting both CUDA and AMD devices must use the **hip*** libraries.
+Users targeting both CUDA and AMD devices must use the **hip*** libraries.
 
 hipBLAS is a BLAS marshaling library with multiple supported backends. It sits between the application and a 'worker' BLAS library, marshalling inputs into the backend library and marshalling results back to the application.
 hipBLAS exports an interface that does not require the client to change, regardless of the chosen backend. Currently, it supports `rocBLAS <https://github.com/ROCmSoftwarePlatform/rocBLAS>`_ and `cuBLAS <https://developer.nvidia.com/cublas>`_ as backends.
diff --git a/docs/source/install.rst → docs/install.rst b/docs/source/install.rst → docs/install.rst
diff --git a/docs/source/orga.rst → docs/orga.rst b/docs/source/orga.rst → docs/orga.rst
diff --git a/docs/run_doc.sh b/docs/run_doc.sh
diff --git a/docs/run_doxygen.sh b/docs/run_doxygen.sh