Sphinx Documentation Setup

Added README links to Python library and CLI tool
Get correct version number from header file
Updated base README with sphinx documentation steps

Change-Id: I60eb3d37d77dab4ff7c8334f94b9c1804edb524b
Signed-off-by: Maisam Arif <Maisam.Arif@amd.com>

README.md

@@ -16,10 +16,12 @@ installed to query firmware information and hardware IPs.
 ### Additional Required software for building
 
 In order to build the AMD SMI library, the following components are required. Note that the software versions listed are what was used in development. Earlier versions are not guaranteed to work:
+
 * CMake (v3.11.0) - `pip3 install cmake`
 * g++ (5.4.0)
 
 In order to build the AMD SMI python package, the following components are required:
+
 * clang (14.0 or above)
 * python (3.6 or above)
 * virtualenv - `pip3 install virtualenv`
@@ -49,10 +51,6 @@ To build the rpm and deb packages follow the above steps with:
 make package
 ```
 
-### Documentation
-
-The reference manual, `refman.pdf` will be in the `latex` directory upon a successful build.
-
 ### Building the Tests
 
 In order to verify the build and capability of AMD SMI on your system and to see an example of how AMD SMI can be used, you may build and run the tests that are available in the repo. To build the tests, follow these steps:
@@ -157,29 +155,46 @@ int main() {
 }
 ```
 
-# Insall Python Library and CLI Tool
+### Documentation
 
-## Requirements
+The reference manual, `AMD_SMI_Manual.pdf` will be in the /opt/rocm/share/doc/amd_smi directory upon a successful build.
 
-- python 3.7+ 64-bit
-- driver must be loaded for amdsmi_init() to pass
+### Sphinx Documentation
 
-## Installation
+To build the documentation locally, run the commands below:
 
-- Install amdgpu driver
-- Install amd-smi-lib package through package manager
-- cd /opt/<rocm_instance>/share/amd_smi
-- python3 -m pip install --upgrade pip
-- python3 -m pip install --user .
-- /opt/<rocm_instance>/bin/amd-smi --help
+``` bash
+cd docs
+
+pip3 install -r sphinx/requirements.txt
+
+python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
+```
+
+The output will be in `docs/_build/html`.
+
+For additional details, see the [ROCm Contributing Guide](https://rocm.docs.amd.com/en/latest/contributing.html#building-documentation)
+
+## Install Python Library and CLI Tool
+
+### Requirements
+
+* python 3.7+ 64-bit
+* driver must be loaded for amdsmi_init() to pass
+
+### Installation
+
+* Install amdgpu driver
+* Install amd-smi-lib package through package manager
+* cd /opt/rocm/share/amd_smi
+* python3 -m pip install --upgrade pip
+* python3 -m pip install --user .
+* /opt/rocm/bin/amd-smi --help
 
 Add /opt/rocm/bin to your shell's path to access amd-smi via the cmdline
 
-## Documentation
+### Rebuilding Python wrapper
 
-Documentation for AMDSMI-CLI is available in /opt/<rocm_instance>/libexec/amdsmi_cli/README.md
-
-## Rebuilding Python wrapper
 The python wrapper (binding) is an auto-generated file `py-interface/amdsmi_wrapper.py`
 
 Wrapper should be re-generated on each C++ API change, by doing:
@@ -195,7 +210,7 @@ Note: To be able to re-generate python wrapper you need several tools installed
 
 Note: python_wrapper is NOT automatically re-generated. You must run `cmake` with `-DBUILD_WRAPPER=on` argument.
 
-# DISCLAIMER
+## DISCLAIMER
 
 The information contained herein is for informational purposes only, and is subject to change without notice. In addition, any stated support is planned and is also subject to change. While every precaution has been taken in the preparation of this document, it may contain technical inaccuracies, omissions and typographical errors, and AMD is under no obligation to update or otherwise correct this information. Advanced Micro Devices, Inc. makes no representations or warranties with respect to the accuracy or completeness of the contents of this document, and assumes no liability of any kind, including the implied warranties of noninfringement, merchantability or fitness for particular purposes, with respect to the operation or use of AMD hardware, software or other products described herein.
 

amdsmi_cli/README.md

@@ -1,4 +1,4 @@
-# AMD System Management Interface
+# AMD SMI CLI Tool
 
 This tool acts as a command line interface for manipulating
 and monitoring the amdgpu kernel, and is intended to replace
@@ -8,17 +8,17 @@ Recommended: At least one AMD GPU with AMD driver installed
 
 ## Requirements
 
-- python 3.7+ 64-bit
-- driver must be loaded for amdsmi_init() to pass
+* python 3.7+ 64-bit
+* driver must be loaded for amdsmi_init() to pass
 
 ## Installation
 
-- Install amdgpu driver
-- Install amd-smi-lib package through package manager
-- cd /opt/<rocm_instance>/share/amd_smi
-- python3 -m pip install --upgrade pip
-- python3 -m pip install --user .
-- /opt/<rocm_instance>/bin/amd-smi --help
+* Install amdgpu driver
+* Install amd-smi-lib package through package manager
+* cd /opt/rocm/share/amd_smi
+* python3 -m pip install --upgrade pip
+* python3 -m pip install --user .
+* /opt/rocm/bin/amd-smi --help
 
 Add /opt/rocm/bin to your shell's path to access amd-smi via the cmdline
 
@@ -34,7 +34,7 @@ Verify that your python version is 3.7+ and if not you can use python3.8 instead
 
 ### Example of Ubuntu 22.04 post amdgpu driver install
 
-```  shell
+``` bash
 apt install amd-smi-lib
 cd /opt/rocm/share/amd_smi
 python3 -m pip install --upgrade pip

docs/amdsmi_cli_readme_link.md

@@ -0,0 +1,2 @@
+```{include} ../amdsmi_cli/README.md
+```

docs/conf.py

@@ -9,11 +9,15 @@ import subprocess
 from rocm_docs import ROCmDocs
 
 
-name = "AMD SMI"
-get_version = r'sed -n -e "s/^get_package_version_number(.*\"\([0-9\.]\{1,\}\).*/\1/p" ../CMakeLists.txt'
-version = subprocess.getoutput(get_version)
-if len(version) > 0:
-    name = f"{name} {version}"
+get_version_year = r'sed -n -e "s/^#define\ AMDSMI_LIB_VERSION_YEAR\ //p" ../include/amd_smi/amdsmi.h'
+get_version_major = r'sed -n -e "s/^#define\ AMDSMI_LIB_VERSION_MAJOR\ //p" ../include/amd_smi/amdsmi.h'
+get_version_minor = r'sed -n -e "s/^#define\ AMDSMI_LIB_VERSION_MINOR\ //p" ../include/amd_smi/amdsmi.h'
+get_version_release = r'sed -n -e "s/^#define\ AMDSMI_LIB_VERSION_RELEASE\ //p" ../include/amd_smi/amdsmi.h'
+version_year = subprocess.getoutput(get_version_year)
+version_major = subprocess.getoutput(get_version_major)
+version_minor = subprocess.getoutput(get_version_minor)
+version_release = subprocess.getoutput(get_version_release)
+name = f"AMD SMI {version_year}.{version_major}.{version_minor}.{version_release}"
 
 external_toc_path = "./sphinx/_toc.yml"
 

docs/doxygen/Doxyfile

@@ -44,7 +44,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "ROCm SMI Reference Manual"
+PROJECT_BRIEF          = "AMD SMI Reference Manual"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55

docs/index.md

@@ -0,0 +1,2 @@
+```{include} ../README.md
+```

docs/index.rst

@@ -1,2 +0,0 @@
-.. include:: ../README.md
-   :parser: myst_parser.sphinx_

docs/py-interface_readme_link.md

@@ -0,0 +1,2 @@
+```{include} ../py-interface/README.md
+```

docs/sphinx/_toc.yml.in

@@ -5,10 +5,16 @@ defaults:
   maxdepth: 6
 root: index
 subtrees:
-  - caption: API
+  - caption: AMD SMI APIs
     entries:
-      - file: doxygen/docBin/html/index
-        title: API
+    - file: doxygen/docBin/html/index
+      title: C
+    - file: py-interface_readme_link
+      title: Python
+  - caption: CLI Tools
+    entries:
+      - file: amdsmi_cli_readme_link
+        title: Python CLI Tool
   - caption: About
     entries:
       - file: license

docs/sphinx/requirements.in

@@ -1 +1 @@
-rocm-docs-core[api_reference]==0.10.3
+rocm-docs-core[api_reference]==0.13.3

docs/sphinx/requirements.txt

@@ -2,7 +2,7 @@
 # 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.4
     # via pydata-sphinx-theme
@@ -43,6 +43,8 @@ docutils==0.19
     #   sphinx
 doxysphinx==3.3.3
     # via rocm-docs-core
+fastjsonschema==2.17.1
+    # via rocm-docs-core
 gitdb==4.0.10
     # via gitpython
 gitpython==3.1.31
@@ -110,13 +112,14 @@ pytz==2023.3
 pyyaml==6.0
     # via
     #   myst-parser
+    #   rocm-docs-core
     #   sphinx-external-toc
 requests==2.30.0
     # via
     #   pygithub
     #   sphinx
-rocm-docs-core[api_reference]==0.10.3
-    # via -r sphinx/requirements.in
+rocm-docs-core[api_reference]==0.13.3
+    # via -r requirements.in
 smmap==5.0.0
     # via gitdb
 snowballstemmer==2.2.0