sphinx documentation

ref: https://github.com/RadeonOpenCompute/rocm_smi_lib/pull/119 fix formatting in docs/index.md Change-Id: I940ef8147a40bd3b702aa591bd56557a870621fb [ROCm/rocm_smi_lib commit: ed74bc6eca]
2023-05-03 16:15:04 -06:00
@@ -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"
@@ -0,0 +1,21 @@
+# 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:
+   install:
+   - requirements: docs/.sphinx/requirements.txt
+
+build:
+   os: ubuntu-20.04
+   tools:
+      python: "3.8"
+   apt_packages:
+     - "doxygen"
+     - "graphviz" # For dot graphs in doxygen
@@ -19,35 +19,50 @@ In order to build the ROCm SMI library, the following components are required. N
 * g++ (5.4.0)

 In order to build the latest documentation, the following are required:
-* DOxygen (1.8.11)
-* latex (pdfTeX 3.14159265-2.6-1.40.16)
+* Python 3.8+
+* NPM (sass)

 The source code for ROCm SMI is available on [Github](https://github.com/RadeonOpenCompute/rocm_smi_lib).

 After the ROCm SMI library git repository has been cloned to a local Linux machine, building the library is achieved by following the typical CMake build sequence. Specifically,
-##### ```$ mkdir -p build```
-##### ```$ cd build```
-##### ```$ cmake <location of root of ROCm SMI library CMakeLists.txt>```
-##### ```$ make```
-##### ```# Install library file and header; default location is /opt/rocm```
-##### ```$ make install```
+```shell
+mkdir -p build
+cd build
+cmake <location of root of ROCm SMI library CMakeLists.txt>
+make
+# Install library file and header; default location is /opt/rocm
+$ make install
+```
 The built library will appear in the `build` folder.

 To build the rpm and deb packages follow the above steps with:
-##### ```$ make package```
+```shell
+make package
+```

 #### Documentation
-The reference manual, `refman.pdf` will be in the `latex` directory upon a successful build.
+The following is an example of how to build the docs:
+```shell
+sudo apt install -y npm
+sudo npm install -g sass
+
+python3 -m venv .venv
+
+.venv/bin/python3 -m pip install -r docs/.sphinx/requirements.txt
+.venv/bin/python3 -m sphinx -T -E -b html -d docs/_build/doctrees -D language=en docs docs/_build/html
+```

 #### Building the Tests
 In order to verify the build and capability of ROCm SMI on your system and to see an example of how ROCm SMI can be used, you may build and run the tests that are available in the repo. To build the tests, follow these steps:

-##### ```# Set environment variables used in CMakeLists.txt file```
-##### ```$ ROCM_DIR=<parent dir. to lib/ and inc/, containing RSMI library and header>```
-##### ```$ mkdir <location for test build>```
-##### ```$ cd <location for test build>```
-##### ```$ cmake -DROCM_DIR=$ROCM_DIR <ROCm SMI source root>/tests/rocm_smi_test```
-##### ```$ make```
+```shell
+# Set environment variables used in CMakeLists.txt file
+ROCM_DIR=<parent dir. to lib/ and inc/, containing RSMI library and header>
+mkdir <location for test build>
+cd <location for test build>
+cmake -DROCM_DIR=$ROCM_DIR <ROCm SMI source root>/tests/rocm_smi_test
+make
+```

 To run the test, execute the program `rsmitst` that is built from the steps above.

@@ -62,7 +77,7 @@ When ROCm-SMI is no longer being used, `rsmi_shut_down()` should be called. This

 A simple "Hello World" type program that displays the device ID of detected devices would look like this:

-```
+```c
 #include <stdint.h>
 #include "rocm_smi/rocm_smi.h"
 int main() {
@@ -86,4 +101,3 @@ int main() {
  return 0;
 }
 ```
-
@@ -0,0 +1,9 @@
+!.sphinx/
+!.doxygen/
+/_build/
+/_doxygen/
+/_images/
+/_static/
+/_templates/
+/html/
+/latex/
@@ -0,0 +1,6 @@
+defaults:
+  numbered: False
+  maxdepth: 6
+root: index
+entries:
+  - file: html/index
@@ -0,0 +1,8 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+defaults:
+  numbered: False
+  maxdepth: 6
+root: index
+entries:
+  - file: html/index
@@ -0,0 +1 @@
+rocm-docs-core[api_reference]==0.9.0
@@ -0,0 +1,165 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile .sphinx/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.34.0
+    # via rocm-docs-core
+certifi==2022.12.7
+    # via requests
+cffi==1.15.1
+    # via
+    #   cryptography
+    #   pynacl
+charset-normalizer==3.1.0
+    # via requests
+click==8.1.3
+    # via
+    #   click-log
+    #   doxysphinx
+    #   sphinx-external-toc
+click-log==0.4.0
+    # via doxysphinx
+cryptography==40.0.2
+    # via pyjwt
+deprecated==1.2.13
+    # via pygithub
+docutils==0.16
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+doxysphinx==3.2.3
+    # 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.4.1
+    # via sphinx
+importlib-resources==5.10.4
+    # via rocm-docs-core
+jinja2==3.1.2
+    # via
+    #   myst-parser
+    #   sphinx
+json5==0.9.11
+    # via doxysphinx
+linkify-it-py==1.0.3
+    # via myst-parser
+lxml==4.9.2
+    # via doxysphinx
+markdown-it-py==2.2.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.2
+    # 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.1
+    # via rocm-docs-core
+pygments==2.15.0
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt[crypto]==2.6.0
+    # via pygithub
+pynacl==1.5.0
+    # via pygithub
+pyparsing==3.0.9
+    # via doxysphinx
+pytz==2023.3
+    # via babel
+pyyaml==6.0
+    # via
+    #   myst-parser
+    #   sphinx-external-toc
+requests==2.28.2
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core[api_reference]==0.9.0
+    # via -r .sphinx/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.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
+typing-extensions==4.5.0
+    # via pydata-sphinx-theme
+uc-micro-py==1.0.1
+    # via linkify-it-py
+urllib3==1.26.15
+    # via requests
+wrapt==1.15.0
+    # via deprecated
+zipp==3.15.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources
@@ -0,0 +1,17 @@
+# 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("ROCm SMI LIB")
+docs_core.run_doxygen(doxygen_root='.doxygen', doxygen_path='.')
+docs_core.enable_api_reference()
+docs_core.setup()
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)
+
+html_theme_options["show_navbar_depth"] = 2
@@ -0,0 +1,3 @@
+# ROCm System Management Interface (ROCm SMI) Library
+
+The ROCm System Management Interface Library, or ROCm SMI library, is part of the Radeon Open Compute [ROCm](https://github.com/RadeonOpenCompute) software stack. It is a C library for Linux that provides a user space interface for applications to monitor and control GPU applications.
@@ -145,38 +145,3 @@ install(FILES ${COMMON_SRC_ROOT}/python_smi_tools/rocm_smi.py
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/bin/rocm-smi
        DESTINATION ${CMAKE_INSTALL_BINDIR}
        COMPONENT dev)
-
-# Generate Doxygen documentation
-find_package(Doxygen)
-find_package(LATEX COMPONENTS PDFLATEX)
-
-if (DOXYGEN_FOUND AND LATEX_FOUND)
-  set (RSMI_MANUAL_NAME "ROCm_SMI_Manual")
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/docs/amd_smi_doxygen.cfg
-                                   ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
-
-  add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.tex
-        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-        DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/docs/amd_smi_doxygen.cfg
-                "${COMMON_INC_DIR}/rocm_smi.h"
-         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
-  add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf
-         COMMAND make  > /dev/null
-         COMMAND cp  ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf
-                  ${CMAKE_CURRENT_SOURCE_DIR}/docs/${RSMI_MANUAL_NAME}_new.pdf
-         DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.tex
-         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/latex)
-
-  add_custom_target(docs DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf)
-
-  add_dependencies(${ROCM_SMI_TARGET} docs)
-  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf
-          DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/${ROCM_SMI} RENAME ${RSMI_MANUAL_NAME}.pdf
-          COMPONENT dev)
-  install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/../README.md
-          DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/${ROCM_SMI}/
-          COMPONENT dev)
-else()
-  message("Doxygen or Latex is not found. Will not generate documents.")
-endif(DOXYGEN_FOUND AND LATEX_FOUND)
-