add configurations for sphinx documentation

Change-Id: I5672348aab0f20d0bfc4dd1efcfecdf4324342d6
2023-05-16 17:14:23 -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"
@@ -17,3 +17,9 @@ docs/*.pdf
 __pycache__/
 *.py[cod]
 *.egg-*
+
+# documentation artifacts
+_toc.yml
+_build/
+_doxygen/
+docBin/
@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+   os: ubuntu-22.04
+   tools:
+      python: "3.8"
+
+sphinx:
+   configuration: docs/conf.py
+
+formats: [htmlzip, pdf, epub]
+
+python:
+   install:
+   - requirements: docs/sphinx/requirements.txt
@@ -0,0 +1,26 @@
+# 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
+
+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}"
+
+external_toc_path = "./sphinx/_toc.yml"
+
+docs_core = ROCmDocs(f"{name} Documentation")
+docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/docBin/xml")
+docs_core.enable_api_reference()
+docs_core.setup()
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)
@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.

-PROJECT_NAME           = "AMDSMI"
+PROJECT_NAME           = AMD SMI

 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -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       =
+OUTPUT_DIRECTORY       = docBin

 # 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
@@ -759,8 +759,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.

-INPUT                = @CMAKE_CURRENT_SOURCE_DIR@/../README.md \
-                     @CMAKE_CURRENT_SOURCE_DIR@/../include/amd_smi/amdsmi.h
+INPUT                = ../../README.md \
+                     ../../include/amd_smi/amdsmi.h

 # 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
@@ -1086,7 +1086,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.

-HTML_HEADER            =
+HTML_HEADER            = ../_doxygen/header.html

 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1096,7 +1096,7 @@ HTML_HEADER            =
 # that doxygen normally uses.
 # This tag requires that the tag GENERATE_HTML is set to YES.

-HTML_FOOTER            =
+HTML_FOOTER            = ../_doxygen/footer.html

 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
 # sheet that is used by each HTML page. It can be used to fine-tune the look of
@@ -1108,7 +1108,7 @@ HTML_FOOTER            =
 # obsolete.
 # This tag requires that the tag GENERATE_HTML is set to YES.

-HTML_STYLESHEET        =
+HTML_STYLESHEET        = ../_doxygen/stylesheet.css

 # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined
 # cascading style sheets that are included after the standard style sheets
@@ -1118,10 +1118,15 @@ HTML_STYLESHEET        =
 # Doxygen will copy the style sheet files to the output directory.
 # Note: The order of the extra style sheet files is of importance (e.g. the last
 # style sheet in the list overrules the setting of the previous ones in the
-# list). For an example see the documentation.
+# list).
+# Note: Since the styling of scrollbars can currently not be overruled in
+# Webkit/Chromium, the styling will be left out of the default doxygen.css if
+# one or more extra stylesheets have been specified. So if scrollbar
+# customization is desired it has to be added explicitly. For an example see the
+# documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.

-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = ../_doxygen/extra_stylesheet.css

 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1521,7 +1526,7 @@ MATHJAX_CODEFILE       =
 # The default value is: YES.
 # This tag requires that the tag GENERATE_HTML is set to YES.

-SEARCHENGINE           = YES
+SEARCHENGINE           = NO

 # When the SERVER_BASED_SEARCH tag is enabled the search engine will be
 # implemented using a web server instead of a web client using Javascript. There
@@ -1875,7 +1880,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.

-GENERATE_XML           = NO
+GENERATE_XML           = YES

 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2072,7 +2077,7 @@ TAGFILES               =
 # tag file that is based on the input files it reads. See section "Linking to
 # external documentation" for more information about the usage of tag files.

-GENERATE_TAGFILE       =
+GENERATE_TAGFILE       = docBin/html/tagfile.xml

 # If the ALLEXTERNALS tag is set to YES, all external class will be listed in
 # the class index. If set to NO, only the inherited external classes will be
@@ -2307,7 +2312,7 @@ DIRECTORY_GRAPH        = YES
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.

-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg

 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
@@ -2319,7 +2324,7 @@ DOT_IMAGE_FORMAT       = png
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.

-INTERACTIVE_SVG        = NO
+INTERACTIVE_SVG        = YES

 # The DOT_PATH tag can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.
@@ -0,0 +1,2 @@
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
@@ -0,0 +1,6 @@
+=======
+License
+=======
+
+.. include:: ../LICENSE
+   :literal:
@@ -0,0 +1,14 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+defaults:
+  numbered: False
+  maxdepth: 6
+root: index
+subtrees:
+  - caption: API
+    entries:
+      - file: doxygen/docBin/html/index
+        title: API
+  - caption: About
+    entries:
+      - file: license
@@ -0,0 +1 @@
+rocm-docs-core[api_reference]==0.10.3
@@ -0,0 +1,172 @@
+#
+# 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.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
+    #   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.19
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+doxysphinx==3.3.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.6.0
+    # via sphinx
+importlib-resources==5.12.0
+    # via rocm-docs-core
+jinja2==3.1.2
+    # via
+    #   myst-parser
+    #   sphinx
+libsass==0.22.0
+    # 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
+mpire==2.7.1
+    # via doxysphinx
+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
+    #   mpire
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjson5==1.6.2
+    # via doxysphinx
+pyjwt[crypto]==2.7.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.30.0
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core[api_reference]==0.10.3
+    # 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.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
+tqdm==4.65.0
+    # via mpire
+typing-extensions==4.5.0
+    # via pydata-sphinx-theme
+uc-micro-py==1.0.2
+    # via linkify-it-py
+urllib3==2.0.2
+    # via requests
+wrapt==1.15.0
+    # via deprecated
+zipp==3.15.0
+    # via
+    #   importlib-metadata
+    #   importlib-resources
@@ -138,39 +138,3 @@ install(
 #                                        DESTINATION libexec/${AMD_SMI})
 #install(FILES ${CMAKE_CURRENT_BINARY_DIR}/bin/rocm-smi
 #                                        DESTINATION bin)
-
-# Generate Doxygen documentation
-find_package(Doxygen)
-find_package(LATEX COMPONENTS PDFLATEX)
-
-if(DOXYGEN_FOUND AND LATEX_FOUND)
-    set(ASMI_MANUAL_NAME "AMD_SMI_Manual")
-    configure_file(${PROJECT_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 ${PROJECT_SOURCE_DIR}/docs/amd_smi_doxygen.cfg "${PROJECT_SOURCE_DIR}/include/amd_smi/amdsmi.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 ${PROJECT_SOURCE_DIR}/docs/${ASMI_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(${AMD_SMI_TARGET} docs)
-    install(
-        FILES ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf
-        DESTINATION share/doc/${AMD_SMI}
-        RENAME ${ASMI_MANUAL_NAME}.pdf
-        COMPONENT dev)
-    install(
-        FILES ${PROJECT_SOURCE_DIR}/README.md
-        DESTINATION share/doc/${AMD_SMI}
-        COMPONENT dev)
-else()
-    message("Doxygen or Latex is not found. Will not generate documents.")
-endif(DOXYGEN_FOUND AND LATEX_FOUND)