From 83bbbd55a30d05e2dcd117625e530a91bcf7cd9b Mon Sep 17 00:00:00 2001 From: "Park, Peter" Date: Fri, 26 Sep 2025 18:30:48 -0400 Subject: [PATCH] docs: Update Doxygen, Sphinx, and readthedocs configs (#719) * conf: update RTD config to ub24.04 (doxygen 1.9.8) and py3.12 * update generate-docs workflow * Update "modules" to "topics" due to Doxygen 1.9.8 * bump rocm-docs-core to 1.25.0 and pip-compile requirements.txt * doxygen: fill in version string in Doxyfile from conf.py * remove unneeded rocm-smi-lib tutorials * remove wikipedia references in doxyfile to satisfy ci check Signed-off-by: Park, Peter [ROCm/amdsmi commit: 311eade5b164d05eff4142b488b4225fa110a0ce] --- .../.github/workflows/generate-docs.yml | 2 +- projects/amdsmi/.readthedocs.yaml | 8 +- projects/amdsmi/docs/conf.py | 27 +- projects/amdsmi/docs/doxygen/.gitignore | 1 + .../docs/doxygen/{Doxyfile => Doxyfile.in} | 288 ++++++++++++------ projects/amdsmi/docs/index.md | 2 +- .../amdsmi/docs/reference/amdsmi-cpp-api.md | 2 +- .../rocm-smi-lib/tutorials/c++_tutorials.rst | 34 --- .../docs/rocm-smi-lib/tutorials/index.rst | 13 - .../rocm-smi-lib/tutorials/python_api.rst | 269 ---------------- .../tutorials/python_tutorials.rst | 29 -- projects/amdsmi/docs/sphinx/_toc.yml.in | 11 +- projects/amdsmi/docs/sphinx/requirements.in | 2 +- projects/amdsmi/docs/sphinx/requirements.txt | 124 ++++---- 14 files changed, 305 insertions(+), 507 deletions(-) rename projects/amdsmi/docs/doxygen/{Doxyfile => Doxyfile.in} (91%) delete mode 100644 projects/amdsmi/docs/rocm-smi-lib/tutorials/c++_tutorials.rst delete mode 100644 projects/amdsmi/docs/rocm-smi-lib/tutorials/index.rst delete mode 100644 projects/amdsmi/docs/rocm-smi-lib/tutorials/python_api.rst delete mode 100644 projects/amdsmi/docs/rocm-smi-lib/tutorials/python_tutorials.rst diff --git a/projects/amdsmi/.github/workflows/generate-docs.yml b/projects/amdsmi/.github/workflows/generate-docs.yml index 88d9836360..9e2ee544b4 100644 --- a/projects/amdsmi/.github/workflows/generate-docs.yml +++ b/projects/amdsmi/.github/workflows/generate-docs.yml @@ -41,7 +41,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: '3.10' + python-version: '3.12' - name: Install System Dependencies run: | diff --git a/projects/amdsmi/.readthedocs.yaml b/projects/amdsmi/.readthedocs.yaml index ced8a98024..935cbdb7ee 100644 --- a/projects/amdsmi/.readthedocs.yaml +++ b/projects/amdsmi/.readthedocs.yaml @@ -4,14 +4,14 @@ version: 2 build: - os: ubuntu-22.04 - tools: - python: "3.10" + os: ubuntu-24.04 + tools: + python: "3.12" sphinx: configuration: docs/conf.py -formats: [htmlzip, pdf, epub] +formats: [htmlzip, pdf] python: install: diff --git a/projects/amdsmi/docs/conf.py b/projects/amdsmi/docs/conf.py index 1bcdce9c22..72dcc2c05e 100644 --- a/projects/amdsmi/docs/conf.py +++ b/projects/amdsmi/docs/conf.py @@ -8,7 +8,8 @@ import re import sys from pathlib import Path -sys.path.append(str(Path('_extension').resolve())) +sys.path.append(str(Path("_extension").resolve())) + # get version number to print in docs def get_version_info(filepath): @@ -47,7 +48,6 @@ release = version_number html_theme = "rocm_docs_theme" html_theme_options = {"flavor": "rocm"} html_title = f"AMD SMI {version_number} documentation" -exclude_patterns = ["rocm-smi-lib"] suppress_warnings = ["etoc.toctree"] external_toc_path = "./sphinx/_toc.yml" @@ -60,3 +60,26 @@ doxygen_project = { "name": "AMD SMI C++ API reference", "path": "doxygen/docBin/xml", } + + +def generate_doxyfile(app, _): + doxyfile_in = Path(app.confdir) / doxygen_root / "Doxyfile.in" + doxyfile_out = Path(app.confdir) / doxygen_root / "Doxyfile" + + if not doxyfile_in.exists(): + from sphinx.errors import ConfigError + + raise ConfigError(f"Missing Doxyfile.in at {doxyfile_in}") + + with open(doxyfile_in) as f: + content = f.read() + + content = content.replace("@PROJECT_NUMBER@", version_number) + + with open(doxyfile_out, "w") as f: + f.write(content) + + +def setup(app): + app.connect("config-inited", generate_doxyfile, priority=100) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/projects/amdsmi/docs/doxygen/.gitignore b/projects/amdsmi/docs/doxygen/.gitignore index 5ebfac1dea..75bdf1c8c6 100644 --- a/projects/amdsmi/docs/doxygen/.gitignore +++ b/projects/amdsmi/docs/doxygen/.gitignore @@ -1 +1,2 @@ docBin/ +Doxyfile diff --git a/projects/amdsmi/docs/doxygen/Doxyfile b/projects/amdsmi/docs/doxygen/Doxyfile.in similarity index 91% rename from projects/amdsmi/docs/doxygen/Doxyfile rename to projects/amdsmi/docs/doxygen/Doxyfile.in index 9b673a31ba..45d7e27d3c 100644 --- a/projects/amdsmi/docs/doxygen/Doxyfile +++ b/projects/amdsmi/docs/doxygen/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.9.6 +# Doxyfile 1.9.8 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -42,19 +42,19 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = AMD SMI +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 # control system is used. -PROJECT_NUMBER = "26.1.0" +PROJECT_NUMBER = @PROJECT_NUMBER@ # Using the PROJECT_BRIEF tag one can provide an optional one line description # 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 = "AMD SMI Tool Guide" +PROJECT_BRIEF = "AMD SMI Library API Guide" # 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 @@ -273,7 +273,7 @@ TAB_SIZE = 4 # with the commands \{ and \} for these it is advised to use the version @{ and # @} or use a double escape (\\{ and \\}) -ALIASES = +ALIASES = "platform{1}=\xrefitem platform \"Platform\" \"Platforms\" \1" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For @@ -353,6 +353,17 @@ MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 5 +# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to +# generate identifiers for the Markdown headings. Note: Every identifier is +# unique. +# Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a +# sequence number starting at 0 and GITHUB use the lower case version of title +# with any whitespace replaced by '-' and punctuation characters removed. +# The default value is: DOXYGEN. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +MARKDOWN_ID_STYLE = DOXYGEN + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or @@ -477,6 +488,14 @@ LOOKUP_CACHE_SIZE = 0 NUM_PROC_THREADS = 1 +# If the TIMESTAMP tag is set different from NO then each generated page will +# contain the date or date and time when the page was generated. Setting this to +# NO can help when comparing the output of multiple runs. +# Possible values are: YES, NO, DATETIME and DATE. +# The default value is: NO. + +TIMESTAMP = NO + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -791,7 +810,7 @@ LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# to be installed. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. @@ -862,7 +881,14 @@ WARN_IF_UNDOC_ENUM_VAL = NO # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS # then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but # at the end of the doxygen process doxygen will return with a non-zero status. -# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then doxygen behaves +# like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined doxygen will not +# write the warning messages in between other messages but write them at the end +# of a run, in case a WARN_LOGFILE is defined the warning messages will be +# besides being in the defined file also be shown at the end of a run, unless +# the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case +# the behavior will remain as with the setting FAIL_ON_WARNINGS. +# Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. WARN_AS_ERROR = NO @@ -907,11 +933,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../reference/index.rst \ - ../../include/amd_smi/amdsmi.h - - - +INPUT = ../reference/index.rst \ + ../../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 @@ -944,12 +967,12 @@ INPUT_FILE_ENCODING = # Note the list of default checked file patterns might differ from the list of # default file extension mappings. # -# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, -# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, -# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, -# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C -# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, -# *.vhdl, *.ucf, *.qsf and *.ice. +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, +# *.cpp, *.cppm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, +# *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.l, *.cs, *.d, *.php, +# *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be +# provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = @@ -989,9 +1012,6 @@ EXCLUDE_PATTERNS = # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* EXCLUDE_SYMBOLS = @@ -1102,13 +1122,13 @@ FORTRAN_COMMENT_AFTER = 72 # also VERBATIM_HEADERS is set to NO. # The default value is: NO. -SOURCE_BROWSER = NO +SOURCE_BROWSER = YES # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. # The default value is: NO. -INLINE_SOURCES = NO +INLINE_SOURCES = YES # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any # special comment blocks from generated source code fragments. Normal C, C++ and @@ -1177,6 +1197,46 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS +# tag is set to YES then doxygen will add the directory of each input to the +# include path. +# The default value is: YES. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1306,8 +1366,8 @@ HTML_COLORSTYLE = AUTO_LIGHT # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to -# this color. Hue is specified as an angle on a color-wheel, see -# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# this color. Hue is specified as an angle on a color-wheel +# For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. @@ -1334,15 +1394,6 @@ HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that # are dynamically created via JavaScript. If disabled, the navigation index will @@ -1362,6 +1413,13 @@ HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO +# If the HTML_CODE_FOLDING tag is set to YES then classes and functions can be +# dynamically folded and expanded in the generated HTML source code. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_CODE_FOLDING = YES + # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to @@ -1492,6 +1550,16 @@ BINARY_TOC = NO TOC_EXPAND = NO +# The SITEMAP_URL tag is used to specify the full URL of the place where the +# generated documentation will be placed on the server by the user during the +# deployment of the documentation. The generated sitemap is called sitemap.xml +# and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL +# is specified no sitemap is generated. For information about the sitemap +# protocol see https://www.sitemaps.org +# This tag requires that the tag GENERATE_HTML is set to YES. + +SITEMAP_URL = + # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help @@ -1980,9 +2048,16 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode -# command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. +# The LATEX_BATCHMODE tag signals the behavior of LaTeX in case of an error. +# Possible values are: NO same as ERROR_STOP, YES same as BATCH, BATCH In batch +# mode nothing is printed on the terminal, errors are scrolled as if is +# hit at every error; missing files that TeX tries to input or request from +# keyboard input (\read on a not open input stream) cause the job to abort, +# NON_STOP In nonstop mode the diagnostic message will appear on the terminal, +# but there is no possibility of user interaction just like in batch mode, +# SCROLL In scroll mode, TeX will stop only for missing files to input or if +# keyboard input is necessary and ERROR_STOP In errorstop mode, TeX will stop at +# each error, asking for user intervention. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1997,20 +2072,12 @@ LATEX_HIDE_INDICES = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See -# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# \cite for more info. # The default value is: plain. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) # path from which the emoji images will be read. If a relative path is entered, # it will be relative to the LATEX_OUTPUT directory. If left blank the @@ -2176,13 +2243,39 @@ DOCBOOK_OUTPUT = docbook #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# AutoGen Definitions (see https://autogen.sourceforge.net/) file that captures # the structure of the code including all documentation. Note that this feature # is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to Sqlite3 output +#--------------------------------------------------------------------------- + +# If the GENERATE_SQLITE3 tag is set to YES doxygen will generate a Sqlite3 +# database with symbols found by doxygen stored in tables. +# The default value is: NO. + +GENERATE_SQLITE3 = NO + +# The SQLITE3_OUTPUT tag is used to specify where the Sqlite3 database will be +# put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put +# in front of it. +# The default directory is: sqlite3. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_OUTPUT = sqlite3 + +# The SQLITE3_OVERWRITE_DB tag is set to YES, the existing doxygen_sqlite3.db +# database file will be recreated with each doxygen run. If set to NO, doxygen +# will warn if an a database file is already found and not modify it. +# The default value is: YES. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_RECREATE_DB = YES + #--------------------------------------------------------------------------- # Configuration options related to the Perl module output #--------------------------------------------------------------------------- @@ -2280,7 +2373,7 @@ INCLUDE_FILE_PATTERNS = # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. PREDEFINED = ENABLE_ESMI_LIB \ - __attribute__(x)= + __attribute__(x)= # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2326,15 +2419,15 @@ TAGFILES = 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 -# listed. +# If the ALLEXTERNALS tag is set to YES, all external classes and namespaces +# will be listed in the class and namespace index. If set to NO, only the +# inherited external classes will be listed. # The default value is: NO. ALLEXTERNALS = NO # If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will be +# in the topic index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. @@ -2348,16 +2441,9 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to diagram generator tools #--------------------------------------------------------------------------- -# You can include diagrams made with dia in doxygen documentation. Doxygen will -# then run dia to produce the diagram and insert it in the documentation. The -# DIA_PATH tag allows you to specify the directory where the dia binary resides. -# If left empty dia is assumed to be found in the default search path. - -DIA_PATH = - # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2366,10 +2452,10 @@ HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: -# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: NO. +# The default value is: YES. HAVE_DOT = NO @@ -2394,7 +2480,7 @@ DOT_NUM_THREADS = 0 # The default value is: fontname=Helvetica,fontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTNAME = Calibri +DOT_COMMON_ATTR = "fontname=Calibri,fontsize=11" # DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can # add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. -o . The external tool should support +# output file formats "png", "eps", "svg", and "ismap". + +MSCGEN_TOOL = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = diff --git a/projects/amdsmi/docs/index.md b/projects/amdsmi/docs/index.md index 3d9879d00a..cd58b91afb 100644 --- a/projects/amdsmi/docs/index.md +++ b/projects/amdsmi/docs/index.md @@ -37,7 +37,7 @@ AMD SMI is the successor to . :::{grid-item-card} Reference * [C++ API](./reference/amdsmi-cpp-api.md) - * [Modules](../doxygen/docBin/html/modules) + * [Modules](../doxygen/docBin/html/topics) * [Files](../doxygen/docBin/html/files) * [Globals](../doxygen/docBin/html/globals) * [Data structures](../doxygen/docBin/html/annotated) diff --git a/projects/amdsmi/docs/reference/amdsmi-cpp-api.md b/projects/amdsmi/docs/reference/amdsmi-cpp-api.md index 6e7f50edb4..ee8fff56bc 100644 --- a/projects/amdsmi/docs/reference/amdsmi-cpp-api.md +++ b/projects/amdsmi/docs/reference/amdsmi-cpp-api.md @@ -11,7 +11,7 @@ This section provides comprehensive documentation for the AMD SMI C++ API. Explore these sections to understand the full scope of available functionalities and how to implement them in your applications. -- {doc}`Modules <../doxygen/docBin/html/modules>` +- {doc}`Modules <../doxygen/docBin/html/topics>` - {doc}`Files <../doxygen/docBin/html/files>` diff --git a/projects/amdsmi/docs/rocm-smi-lib/tutorials/c++_tutorials.rst b/projects/amdsmi/docs/rocm-smi-lib/tutorials/c++_tutorials.rst deleted file mode 100644 index 884b133657..0000000000 --- a/projects/amdsmi/docs/rocm-smi-lib/tutorials/c++_tutorials.rst +++ /dev/null @@ -1,34 +0,0 @@ -==================== -C++ Tutorials -==================== - -This chapter contains the ROCm SMI C++ API tutorials. - -.. code-block:: c++ - - #include - #include "rocm_smi/rocm_smi.h" - int main() { - - rsmi_status_t ret; - uint32_t num_devices; - uint16_t dev_id; - - // We will skip return code checks for this example, but it - // is recommended to always check this as some calls may not - // apply for some devices or ROCm releases - - ret = rsmi_init(0); - ret = rsmi_num_monitor_devices(&num_devices); - - for (int i=0; i < num_devices; ++i) { - ret = rsmi_dev_id_get(i, &dev_id); - // dev_id holds the device ID of device i, upon a - // successful call - } - ret = rsmi_shut_down(); - return 0; - } - -For more examples please check the `C++ example `_ -or `tests. `_ diff --git a/projects/amdsmi/docs/rocm-smi-lib/tutorials/index.rst b/projects/amdsmi/docs/rocm-smi-lib/tutorials/index.rst deleted file mode 100644 index a0915ee846..0000000000 --- a/projects/amdsmi/docs/rocm-smi-lib/tutorials/index.rst +++ /dev/null @@ -1,13 +0,0 @@ - -.. meta:: - :description: ROCm SMI documentation and API reference library - :keywords: SMI, ROCm, API, documentation - - -**************************************************** -ROCm System Management Interface (ROCm SMI) library -**************************************************** - -The ROCm System Management Interface Library, or ROCm SMI library, is part of the ROCm software stack. It is a C library for Linux that provides a user space interface for applications to monitor and control GPU applications. - -ROCm SMI Library still works in the current release, but its documentation is now integrated with AMD SMI. For information specific to ROCm SMI Library, refer to `ROCm SMI Library `_ diff --git a/projects/amdsmi/docs/rocm-smi-lib/tutorials/python_api.rst b/projects/amdsmi/docs/rocm-smi-lib/tutorials/python_api.rst deleted file mode 100644 index 604803b9c0..0000000000 --- a/projects/amdsmi/docs/rocm-smi-lib/tutorials/python_api.rst +++ /dev/null @@ -1,269 +0,0 @@ -==================== -Python API Reference -==================== - -This chapter describes the ROCm SMI Python module API. - -.. default-domain:: py -.. py:currentmodule:: rocm_smi - -Functions ---------- - -.. autofunction:: rocm_smi.driverInitialized - -.. autofunction:: rocm_smi.formatJson - -.. autofunction:: rocm_smi.formatCsv - -.. autofunction:: rocm_smi.formatMatrixToJSON - -.. autofunction:: rocm_smi.getBus - -.. autofunction:: rocm_smi.getFanSpeed - -.. autofunction:: rocm_smi.getGpuUse - -.. autofunction:: rocm_smi.getDRMDeviceId - -.. autofunction:: rocm_smi.getSubsystemId - -.. autofunction:: rocm_smi.getVendor - -.. autofunction:: rocm_smi.getGUID - -.. autofunction:: rocm_smi.getTargetGfxVersion - -.. autofunction:: rocm_smi.getNodeId - -.. autofunction:: rocm_smi.getDeviceName - -.. autofunction:: rocm_smi.getRev - -.. autofunction:: rocm_smi.getMaxPower - -.. autofunction:: rocm_smi.getMemInfo - -.. autofunction:: rocm_smi.getProcessName - -.. autofunction:: rocm_smi.getPerfLevel - -.. autofunction:: rocm_smi.getPid - -.. autofunction:: rocm_smi.getPidList - -.. autofunction:: rocm_smi.getPower - -.. autofunction:: rocm_smi.getRasEnablement - -.. autofunction:: rocm_smi.getTemp - -.. autofunction:: rocm_smi.findFirstAvailableTemp - -.. autofunction:: rocm_smi.getTemperatureLabel - -.. autofunction:: rocm_smi.getPowerLabel - -.. autofunction:: rocm_smi.getVbiosVersion - -.. autofunction:: rocm_smi.getVersion - -.. autofunction:: rocm_smi.getComputePartition - -.. autofunction:: rocm_smi.getMemoryPartition - -.. autofunction:: rocm_smi.print2DArray - -.. autofunction:: rocm_smi.printEmptyLine - -.. autofunction:: rocm_smi.printErrLog - -.. autofunction:: rocm_smi.printInfoLog - -.. autofunction:: rocm_smi.printEventList - -.. autofunction:: rocm_smi.printLog - -.. autofunction:: rocm_smi.printListLog - -.. autofunction:: rocm_smi.printLogSpacer - -.. autofunction:: rocm_smi.printSysLog - -.. autofunction:: rocm_smi.printTableLog - -.. autofunction:: rocm_smi.printTableRow - -.. autofunction:: rocm_smi.checkIfSecondaryDie - -.. autofunction:: rocm_smi.resetClocks - -.. autofunction:: rocm_smi.resetFans - -.. autofunction:: rocm_smi.resetPowerOverDrive - -.. autofunction:: rocm_smi.resetProfile - -.. autofunction:: rocm_smi.resetXgmiErr - -.. autofunction:: rocm_smi.resetPerfDeterminism - -.. autofunction:: rocm_smi.resetComputePartition - -.. autofunction:: rocm_smi.resetMemoryPartition - -.. autofunction:: rocm_smi.setClockRange - -.. autofunction:: rocm_smi.setClockExtremum - -.. autofunction:: rocm_smi.setVoltageCurve - -.. autofunction:: rocm_smi.setPowerPlayTableLevel - -.. autofunction:: rocm_smi.setClockOverDrive - -.. autofunction:: rocm_smi.setClocks - -.. autofunction:: rocm_smi.setPerfDeterminism - -.. autofunction:: rocm_smi.resetGpu - -.. autofunction:: rocm_smi.isRasControlAvailable - -.. autofunction:: rocm_smi.setRas - -.. autofunction:: rocm_smi.setFanSpeed - -.. autofunction:: rocm_smi.setPerformanceLevel - -.. autofunction:: rocm_smi.setPowerOverDrive - -.. autofunction:: rocm_smi.setProfile - -.. autofunction:: rocm_smi.setComputePartition - -.. autofunction:: rocm_smi.progressbar - -.. autofunction:: rocm_smi.showProgressbar - -.. autofunction:: rocm_smi.setMemoryPartition - -.. autofunction:: rocm_smi.showVersion - -.. autofunction:: rocm_smi.showAllConcise - -.. autofunction:: rocm_smi.showAllConciseHw - -.. autofunction:: rocm_smi.showBus - -.. autofunction:: rocm_smi.showClocks - -.. autofunction:: rocm_smi.showCurrentClocks - -.. autofunction:: rocm_smi.showCurrentFans - -.. autofunction:: rocm_smi.showCurrentTemps - -.. autofunction:: rocm_smi.showFwInfo - -.. autofunction:: rocm_smi.showGpusByPid - -.. autofunction:: rocm_smi.getCoarseGrainUtil - -.. autofunction:: rocm_smi.showGpuUse - -.. autofunction:: rocm_smi.showEnergy - -.. autofunction:: rocm_smi.showId - -.. autofunction:: rocm_smi.showMaxPower - -.. autofunction:: rocm_smi.showMemInfo - -.. autofunction:: rocm_smi.showMemUse - -.. autofunction:: rocm_smi.showMemVendor - -.. autofunction:: rocm_smi.showOverDrive - -.. autofunction:: rocm_smi.showPcieBw - -.. autofunction:: rocm_smi.showPcieReplayCount - -.. autofunction:: rocm_smi.showPerformanceLevel - -.. autofunction:: rocm_smi.showPids - -.. autofunction:: rocm_smi.showPower - -.. autofunction:: rocm_smi.showPowerPlayTable - -.. autofunction:: rocm_smi.showProduct - -.. autofunction:: rocm_smi.showProfile - -.. autofunction:: rocm_smi.showRange - -.. autofunction:: rocm_smi.showRasInfo - -.. autofunction:: rocm_smi.showRetiredPages - -.. autofunction:: rocm_smi.showSerialNumber - -.. autofunction:: rocm_smi.showUId - -.. autofunction:: rocm_smi.showVbiosVersion - -.. autofunction:: rocm_smi.showEvents - -.. autofunction:: rocm_smi.showDriverVersion - -.. autofunction:: rocm_smi.showVoltage - -.. autofunction:: rocm_smi.showVoltageCurve - -.. autofunction:: rocm_smi.showXgmiErr - -.. autofunction:: rocm_smi.showAccessibleTopology - -.. autofunction:: rocm_smi.showWeightTopology - -.. autofunction:: rocm_smi.showHopsTopology - -.. autofunction:: rocm_smi.showTypeTopology - -.. autofunction:: rocm_smi.showNumaTopology - -.. autofunction:: rocm_smi.showHwTopology - -.. autofunction:: rocm_smi.showNodesBw - -.. autofunction:: rocm_smi.showComputePartition - -.. autofunction:: rocm_smi.showMemoryPartition - -.. autofunction:: rocm_smi.checkAmdGpus - -.. autofunction:: rocm_smi.component_str - -.. autofunction:: rocm_smi.confirmOutOfSpecWarning - -.. autofunction:: rocm_smi.doesDeviceExist - -.. autofunction:: rocm_smi.initializeRsmi - -.. autofunction:: rocm_smi.isAmdDevice - -.. autofunction:: rocm_smi.listDevices - -.. autofunction:: rocm_smi.load - -.. autofunction:: rocm_smi.padHexValue - -.. autofunction:: rocm_smi.profileString - -.. autofunction:: rocm_smi.relaunchAsSudo - -.. autofunction:: rocm_smi.rsmi_ret_ok - -.. autofunction:: rocm_smi.save diff --git a/projects/amdsmi/docs/rocm-smi-lib/tutorials/python_tutorials.rst b/projects/amdsmi/docs/rocm-smi-lib/tutorials/python_tutorials.rst deleted file mode 100644 index 78a4a43db2..0000000000 --- a/projects/amdsmi/docs/rocm-smi-lib/tutorials/python_tutorials.rst +++ /dev/null @@ -1,29 +0,0 @@ -==================== -Python Tutorials -==================== - -This chapter is the rocm_smi Python api tutorials. - -.. code-block:: python - - import sys - sys.path.append("/opt/rocm/libexec/rocm_smi/") - try: - import rocm_smi - except ImportError: - raise ImportError("Could not import /opt/rocm/libexec/rocm_smi/rocm_smi.py") - - class prof_utils: - def __init__(self, mode) -> None: - rocm_smi.initializeRsmi() - - def getPower(self, device): - return rocm_smi.getPower(device) - - def listDevices(self): - return rocm_smi.listDevices() - - def getMemInfo(self, device): - (memUsed, memTotal) = rocm_smi.getMemInfo(device, "vram") - return round(float(memUsed)/float(memTotal) * 100, 2) - diff --git a/projects/amdsmi/docs/sphinx/_toc.yml.in b/projects/amdsmi/docs/sphinx/_toc.yml.in index 7e7eaebc40..13f864206e 100644 --- a/projects/amdsmi/docs/sphinx/_toc.yml.in +++ b/projects/amdsmi/docs/sphinx/_toc.yml.in @@ -1,3 +1,10 @@ +# Variables of the form ${} are substituted, currently the following +# list is supported: +# - ${branch} (or {branch}) the name of the current branch +# - ${url} (or {url}) github url of the current project +# - ${project:} base url of the documentation of +# based on intersphinx_mapping. +# These comments will also be removed. defaults: numbered: false root: index @@ -27,7 +34,7 @@ subtrees: - file: reference/amdsmi-cpp-api.md title: C++ API entries: - - file: doxygen/docBin/html/modules + - file: doxygen/docBin/html/topics title: Modules - file: doxygen/docBin/html/files title: Files @@ -50,7 +57,7 @@ subtrees: - caption: Tutorials entries: - - url: https://github.com/ROCm/amdsmi/tree/amd-staging/example + - url: https://github.com/ROCm/amdsmi/tree/${branch}/example title: AMD SMI examples (GitHub) - url: https://rocm.blogs.amd.com/software-tools-optimization/amd-smi-overview/README.html title: AMD SMI CLI walkthrough diff --git a/projects/amdsmi/docs/sphinx/requirements.in b/projects/amdsmi/docs/sphinx/requirements.in index 73a3602786..7002c7c9d9 100644 --- a/projects/amdsmi/docs/sphinx/requirements.in +++ b/projects/amdsmi/docs/sphinx/requirements.in @@ -1 +1 @@ -rocm-docs-core[api_reference]==1.20.1 +rocm-docs-core[api_reference]==1.25.0 diff --git a/projects/amdsmi/docs/sphinx/requirements.txt b/projects/amdsmi/docs/sphinx/requirements.txt index a4fa82e3a7..a774b31e5f 100644 --- a/projects/amdsmi/docs/sphinx/requirements.txt +++ b/projects/amdsmi/docs/sphinx/requirements.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.12 # by the following command: # # pip-compile docs/sphinx/requirements.in @@ -10,7 +10,7 @@ alabaster==1.0.0 # via sphinx asttokens==3.0.0 # via stack-data -attrs==25.1.0 +attrs==25.3.0 # via # jsonschema # jupyter-cache @@ -19,19 +19,19 @@ babel==2.17.0 # via # pydata-sphinx-theme # sphinx -beautifulsoup4==4.13.3 +beautifulsoup4==4.13.5 # via pydata-sphinx-theme breathe==4.36.0 # via rocm-docs-core -certifi==2025.1.31 +certifi==2025.8.3 # via requests -cffi==1.17.1 +cffi==2.0.0 # via # cryptography # pynacl -charset-normalizer==3.4.1 +charset-normalizer==3.4.3 # via requests -click==8.1.8 +click==8.3.0 # via # click-log # doxysphinx @@ -39,20 +39,18 @@ click==8.1.8 # sphinx-external-toc click-log==0.4.0 # via doxysphinx -comm==0.2.2 +comm==0.2.3 # via ipykernel -contourpy==1.3.1 +contourpy==1.3.3 # via matplotlib -cryptography==44.0.1 +cryptography==46.0.1 # via pyjwt cycler==0.12.1 # via matplotlib -debugpy==1.8.12 +debugpy==1.8.17 # via ipykernel decorator==5.2.1 # via ipython -deprecated==1.2.18 - # via pygithub docutils==0.21.2 # via # myst-parser @@ -60,45 +58,45 @@ docutils==0.21.2 # sphinx doxysphinx==3.3.12 # via rocm-docs-core -exceptiongroup==1.2.2 - # via ipython -executing==2.2.0 +executing==2.2.1 # via stack-data -fastjsonschema==2.21.1 +fastjsonschema==2.21.2 # via # nbformat # rocm-docs-core -fonttools==4.56.0 +fonttools==4.60.0 # via matplotlib gitdb==4.0.12 # via gitpython -gitpython==3.1.44 +gitpython==3.1.45 # via rocm-docs-core -greenlet==3.1.1 +greenlet==3.2.4 # via sqlalchemy idna==3.10 # via requests imagesize==1.4.1 # via sphinx -importlib-metadata==8.6.1 +importlib-metadata==8.7.0 # via # jupyter-cache # myst-nb -ipykernel==6.29.5 +ipykernel==6.30.1 # via myst-nb -ipython==8.33.0 +ipython==9.5.0 # via # ipykernel # myst-nb +ipython-pygments-lexers==1.1.1 + # via ipython jedi==0.19.2 # via ipython jinja2==3.1.6 # via # myst-parser # sphinx -jsonschema==4.23.0 +jsonschema==4.25.1 # via nbformat -jsonschema-specifications==2024.10.1 +jsonschema-specifications==2025.9.1 # via jsonschema jupyter-cache==1.0.1 # via myst-nb @@ -106,13 +104,13 @@ jupyter-client==8.6.3 # via # ipykernel # nbclient -jupyter-core==5.7.2 +jupyter-core==5.8.1 # via # ipykernel # jupyter-client # nbclient # nbformat -kiwisolver==1.4.8 +kiwisolver==1.4.9 # via matplotlib libsass==0.22.0 # via doxysphinx @@ -124,19 +122,19 @@ markdown-it-py==3.0.0 # myst-parser markupsafe==3.0.2 # via jinja2 -matplotlib==3.10.1 +matplotlib==3.10.6 # via doxysphinx matplotlib-inline==0.1.7 # via # ipykernel # ipython -mdit-py-plugins==0.4.2 +mdit-py-plugins==0.5.0 # via myst-parser mdurl==0.1.2 # via markdown-it-py mpire==2.10.2 # via doxysphinx -myst-nb==1.2.0 +myst-nb==1.3.0 # via rocm-docs-core myst-parser==4.0.1 # via myst-nb @@ -156,50 +154,50 @@ numpy==1.26.4 # contourpy # doxysphinx # matplotlib -packaging==24.2 +packaging==25.0 # via # ipykernel # matplotlib - # pydata-sphinx-theme # sphinx -parso==0.8.4 +parso==0.8.5 # via jedi pexpect==4.9.0 # via ipython -pillow==11.1.0 +pillow==11.3.0 # via matplotlib -platformdirs==4.3.6 +platformdirs==4.4.0 # via jupyter-core -prompt-toolkit==3.0.50 +prompt-toolkit==3.0.52 # via ipython -psutil==7.0.0 +psutil==7.1.0 # via ipykernel ptyprocess==0.7.0 # via pexpect pure-eval==0.2.3 # via stack-data -pycparser==2.22 +pycparser==2.23 # via cffi -pydata-sphinx-theme==0.15.4 +pydata-sphinx-theme==0.16.1 # via # rocm-docs-core # sphinx-book-theme -pygithub==2.6.1 +pygithub==2.8.1 # via rocm-docs-core -pygments==2.19.1 +pygments==2.19.2 # via # accessible-pygments # ipython + # ipython-pygments-lexers # mpire # pydata-sphinx-theme # sphinx -pyjson5==1.6.8 +pyjson5==1.6.9 # via doxysphinx pyjwt[crypto]==2.10.1 # via pygithub -pynacl==1.5.0 +pynacl==1.6.0 # via pygithub -pyparsing==3.2.1 +pyparsing==3.2.5 # via # doxysphinx # matplotlib @@ -207,14 +205,14 @@ python-dateutil==2.9.0.post0 # via # jupyter-client # matplotlib -pyyaml==6.0.2 +pyyaml==6.0.3 # via # jupyter-cache # myst-nb # myst-parser # rocm-docs-core # sphinx-external-toc -pyzmq==26.2.1 +pyzmq==27.1.0 # via # ipykernel # jupyter-client @@ -222,13 +220,15 @@ referencing==0.36.2 # via # jsonschema # jsonschema-specifications -requests==2.32.4 +requests==2.32.5 # via # pygithub # sphinx -rocm-docs-core[api-reference]==1.20.1 - # via -r requirements.in -rpds-py==0.23.1 +rocm-docs-core[api-reference]==1.25.0 + # via -r docs/sphinx/requirements.in +roman-numerals-py==3.1.0 + # via sphinx +rpds-py==0.27.1 # via # jsonschema # referencing @@ -236,11 +236,11 @@ six==1.17.0 # via python-dateutil smmap==5.0.2 # via gitdb -snowballstemmer==2.2.0 +snowballstemmer==3.0.1 # via sphinx -soupsieve==2.6 +soupsieve==2.8 # via beautifulsoup4 -sphinx==8.1.3 +sphinx==8.2.3 # via # breathe # myst-nb @@ -252,7 +252,7 @@ sphinx==8.1.3 # sphinx-design # sphinx-external-toc # sphinx-notfound-page -sphinx-book-theme==1.1.4 +sphinx-book-theme==1.1.3 # via rocm-docs-core sphinx-copybutton==0.5.2 # via rocm-docs-core @@ -274,15 +274,13 @@ sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx -sqlalchemy==2.0.38 +sqlalchemy==2.0.43 # via jupyter-cache stack-data==0.6.3 # via ipython tabulate==0.9.0 # via jupyter-cache -tomli==2.2.1 - # via sphinx -tornado==6.5.1 +tornado==6.5.2 # via # ipykernel # jupyter-client @@ -290,7 +288,6 @@ tqdm==4.67.1 # via mpire traitlets==5.14.3 # via - # comm # ipykernel # ipython # jupyter-client @@ -298,10 +295,9 @@ traitlets==5.14.3 # matplotlib-inline # nbclient # nbformat -typing-extensions==4.12.2 +typing-extensions==4.15.0 # via # beautifulsoup4 - # ipython # myst-nb # pydata-sphinx-theme # pygithub @@ -311,9 +307,7 @@ urllib3==2.5.0 # via # pygithub # requests -wcwidth==0.2.13 +wcwidth==0.2.14 # via prompt-toolkit -wrapt==1.17.2 - # via deprecated -zipp==3.21.0 +zipp==3.23.0 # via importlib-metadata