Standardize documentation for ReadtheDocs

.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

@@ -42,7 +42,6 @@ _images/
 _static/
 _templates/
 _toc.yml
-docBin/
 
 # matrices
 *.csr

.readthedocs.yaml

@@ -6,13 +6,13 @@ version: 2
 sphinx:
    configuration: docs/conf.py
 
-formats: [htmlzip]
+formats: [htmlzip, pdf, epub]
 
 python:
    install:
-   - requirements: docs/.sphinx/requirements.txt
+   - requirements: docs/sphinx/requirements.txt
 
 build:
-   os: ubuntu-20.04
+   os: ubuntu-22.04
    tools:
       python: "3.8"

README.md

@@ -46,7 +46,7 @@ Run the steps below to build documentation locally.
 ```bash
 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
 ```

clients/gtest/README.md

@@ -1,7 +1,8 @@
 # Gtest
+
 hipblaslt-test is the main regression gtest for hipBLASLt. All test items should pass.
 
-```
+```shell
 # Go to hipBLASLt build directory
 cd hipBLASLt; cd build/release
 
@@ -13,5 +14,4 @@ cd hipBLASLt; cd build/release
 
 # Demo: gtest tests with filter
 ./clients/staging/hipblaslt-test --gtest_filter=*quick*
-
 ```

docs/.gitignore

@@ -1,2 +1,2 @@
-docBin
+_build/
 _doxygen/

docs/conf.py

@@ -4,11 +4,32 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+
+import re
+
 from rocm_docs import ROCmDocs
 
-docs_core = ROCmDocs("hipBLASLt Documentation")
-docs_core.run_doxygen()
+with open('../CMakeLists.txt', encoding='utf-8') as f:
+    match = re.search(r'.*\bset\(VERSION_STRING\s+\"?([0-9.]+)[^0-9.]+', f.read())
+    if not match:
+        raise ValueError("VERSION not found!")
+    version_number = match[1]
+left_nav_title = f"hipBLASLt {version_number} Documentation"
+
+# for PDF output on Read the Docs
+project = "hipBLASLt Documentation"
+author = "Advanced Micro Devices, Inc."
+copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved."
+version = version_number
+release = version_number
+
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(left_nav_title)
+docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml")
 docs_core.setup()
 
+external_projects_current_project = "hipblaslt"
+
 for sphinx_var in ROCmDocs.SPHINX_VARS:
     globals()[sphinx_var] = getattr(docs_core, sphinx_var)

docs/datatypes.rst

@@ -11,7 +11,7 @@ hipblasLtEpilogue_t
 .. doxygenenum:: hipblasLtEpilogue_t
 
 hipblasLtPointerMode_t
--------------------
+----------------------
 .. doxygenenum:: hipblasLtPointerMode_t
 
 hipblasLtHandle_t

docs/doxygen/.gitignore

@@ -0,0 +1,2 @@
+html/
+xml/

docs/.doxygen/Doxyfile → docs/doxygen/Doxyfile

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = docBin
+OUTPUT_DIRECTORY       = .
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -963,7 +963,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
@@ -2190,7 +2190,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: NO.
 
-HAVE_DOT               = YES
+HAVE_DOT               = NO
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of

docs/ext-ops.rst

@@ -3,7 +3,7 @@ hipBLASLtExt Operation Reference
 ********************************
 
 hipBLASLtExt Operation API Reference
-================================
+====================================
 
 hipblasltExtSoftmax()
 ------------------------------------------

docs/functions.rst

@@ -74,14 +74,14 @@ Datatypes Supported:
 
 hipblasLtMatmul supports the following computeType, scaleType, Atype/Btype, Ctype/Dtype and Bias Type:
 
-======================= =================== ============= ==============
-computeType             scaleType/Bias Type Atype/Btype   Ctype/Dtype
-======================= =================== ============= ==============
-HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F       HIPBLASLT_R_32F HIPBLASLT_R_32F
-HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F       HIPBLASLT_R_16F HIPBLASLT_R_16F
-HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F       HIPBLASLT_R_16F HIPBLASLT_R_32F
-HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F       HIPBLASLT_R_16B HIPBLASLT_R_16B
-======================= =================== ============= ==============
+======================= =================== =============== ===============
+computeType             scaleType/Bias Type Atype/Btype     Ctype/Dtype
+======================= =================== =============== ===============
+HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F     HIPBLASLT_R_32F HIPBLASLT_R_32F
+HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F     HIPBLASLT_R_16F HIPBLASLT_R_16F
+HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F     HIPBLASLT_R_16F HIPBLASLT_R_32F
+HIPBLASLT_COMPUTE_F32   HIPBLASLT_R_32F     HIPBLASLT_R_16B HIPBLASLT_R_16B
+======================= =================== =============== ===============
 
 hipblasLtMatrixTransformDescCreate()
 ------------------------------------------

docs/index.rst

@@ -78,5 +78,5 @@ To overcome this overhead, it is recommended to query the heuristics once using
 
 
 hipBLASLt Extensions
-================
+====================
 See extension reference page for more information.

docs/license.rst

@@ -0,0 +1,4 @@
+License
+=======
+
+.. include:: ../LICENSE.md

docs/.sphinx/_toc.yml.in → docs/sphinx/_toc.yml.in

@@ -11,3 +11,6 @@ subtrees:
     - file: usage
     - file: ext-ops
     - file: clients
+  - caption: About
+    entries:
+    - file: license

docs/sphinx/requirements.in

@@ -0,0 +1 @@
+rocm-docs-core==0.30.3

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

@@ -84,9 +84,7 @@ pygments==2.15.0
     #   pydata-sphinx-theme
     #   sphinx
 pyjwt[crypto]==2.6.0
-    # via
-    #   pygithub
-    #   pyjwt
+    # via pygithub
 pynacl==1.5.0
     # via pygithub
 pytz==2023.3.post1

docs/usage.rst

@@ -476,7 +476,7 @@ The following is a simple example of how this API works.
     }
 
 The base class (GemmInstance)
---------------
+-----------------------------
 
 This is the base class of class Gemm and GroupedGemm.
 
@@ -497,7 +497,7 @@ This is the base class of class Gemm and GroupedGemm.
     HIPBLASLT_EXPORT hipblasStatus_t run(hipStream_t stream);
 
 Get all algorithms
---------------
+------------------
 
 Get all algorithms lets users to get all the algorithms of a specific problem type. It requires the transpose of A, B, the data type of the inputs, and the compute type.
 
@@ -708,7 +708,7 @@ Grouped gemm
     }
 
 Algorithm Index
---------------
+---------------
 
 The extension API lets user to get the algorithm index from hipblasLtMatmulAlgo_t.
 
@@ -731,6 +731,7 @@ Example code
 ^^^^^^^^^^^^
 
 .. code-block:: c++
+
     int index = hipblaslt_ext::getIndexFromAlgo(testResults[i].algo);
     // Save the index to disk or somewhere else for later use.
 
@@ -739,9 +740,8 @@ Example code
     std::vector<hipblasLtMatmulHeuristicResult_t> heuristicResults;
     CHECK_HIPBLASLT_ERROR(hipblaslt_ext::getAlgosFromIndex(handle, algoIndex, heuristicResults));
 
-
 [Grouped Gemm] Fixed MK
---------------
+-----------------------
 
 hipBLASLt extension supports changing the sizes (m, n, k, batch) from the device memory "UserArguments", but the setup is a bit different from the normal routing.
 
@@ -751,6 +751,7 @@ Sum of n
 A sum of N is required to use as an input for the grouped gemm instance.
 
 .. code-block:: c++
+
     {1000, 1, 1, 1}; // The array of N, the first element is the sum of N
 
     // Below is the values stored in "UserArguments"