From c5e06b404048c431acd4e911083271308a5072db Mon Sep 17 00:00:00 2001 From: Sam Wu Date: Tue, 16 May 2023 17:14:23 -0600 Subject: [PATCH] add configurations for sphinx documentation Change-Id: I5672348aab0f20d0bfc4dd1efcfecdf4324342d6 --- .github/dependabot.yml | 12 ++ .gitignore | 6 + .readthedocs.yaml | 18 ++ docs/conf.py | 26 +++ .../{amd_smi_doxygen.cfg => doxygen/Doxyfile} | 33 ++-- docs/index.rst | 2 + docs/license.rst | 6 + docs/sphinx/_toc.yml.in | 14 ++ docs/sphinx/requirements.in | 1 + docs/sphinx/requirements.txt | 172 ++++++++++++++++++ src/CMakeLists.txt | 36 ---- 11 files changed, 276 insertions(+), 50 deletions(-) create mode 100644 .github/dependabot.yml create mode 100644 .readthedocs.yaml create mode 100644 docs/conf.py rename docs/{amd_smi_doxygen.cfg => doxygen/Doxyfile} (99%) create mode 100644 docs/index.rst create mode 100644 docs/license.rst create mode 100644 docs/sphinx/_toc.yml.in create mode 100644 docs/sphinx/requirements.in create mode 100644 docs/sphinx/requirements.txt diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000000..276690bd4f --- /dev/null +++ b/.github/dependabot.yml @@ -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" diff --git a/.gitignore b/.gitignore index 5b157b6f4b..28441fe2f8 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,9 @@ docs/*.pdf __pycache__/ *.py[cod] *.egg-* + +# documentation artifacts +_toc.yml +_build/ +_doxygen/ +docBin/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..5f50df2525 --- /dev/null +++ b/.readthedocs.yaml @@ -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 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..f77158e731 --- /dev/null +++ b/docs/conf.py @@ -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) diff --git a/docs/amd_smi_doxygen.cfg b/docs/doxygen/Doxyfile similarity index 99% rename from docs/amd_smi_doxygen.cfg rename to docs/doxygen/Doxyfile index 3e9779a09a..a35063a3ab 100644 --- a/docs/amd_smi_doxygen.cfg +++ b/docs/doxygen/Doxyfile @@ -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. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..339dc8f42d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,2 @@ +.. include:: ../README.md + :parser: myst_parser.sphinx_ diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000000..ddb544496e --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,6 @@ +======= +License +======= + +.. include:: ../LICENSE + :literal: diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in new file mode 100644 index 0000000000..7d534c0601 --- /dev/null +++ b/docs/sphinx/_toc.yml.in @@ -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 diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in new file mode 100644 index 0000000000..0c3a8febc3 --- /dev/null +++ b/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core[api_reference]==0.10.3 diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt new file mode 100644 index 0000000000..630360bde9 --- /dev/null +++ b/docs/sphinx/requirements.txt @@ -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 diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 07b45cf3b4..430a374459 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -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)