From be8b02b93ec088669d88b0430ba1ba304a4f08c2 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:06:48 -0400 Subject: [PATCH 1/9] update conf.py to non-legacy rocm docs setup --- docs/conf.py | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 718797ac1..f350e4f18 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,29 +28,31 @@ import re -from rocm_docs import ROCmDocs - with open("../VERSION", encoding="utf-8") as f: match = re.search(r"([0-9.]+)[^0-9.]+", f.read()) if not match: raise ValueError("VERSION not found!") version_number = match[1] -external_projects_current_project = "omnitrace" - -project = "omnitrace" +# project info +project = "Omniperf" author = "Advanced Micro Devices, Inc." copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved." version = version_number release = version_number -html_title = f"Omnitrace {version} documentation" -external_toc_path = "./sphinx/_toc.yml" +extensions = ["rocm_docs", "rocm_docs.doxygen", "sphinxcontrib.datatemplates"] +html_theme = "rocm_docs_theme" +html_theme_options = {"flavor": "rocm"} +html_title = f"Omnitrace {version_number} documentation" -docs_core = ROCmDocs(html_title) -docs_core.setup() -docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") -docs_core.enable_api_reference() +external_toc_path = "./sphinx/_toc.yml" +external_projects_current_project = "omnitrace" -for sphinx_var in ROCmDocs.SPHINX_VARS: - globals()[sphinx_var] = getattr(docs_core, sphinx_var) +doxygen_root = "doxygen" +doxysphinx_enabled = True +doxygen_project = { + "name": "ROCm Docs Core Test Project - Extension", + "path": "doxygen/xml", +} +external_projects_remote_repository = "" From 6598b020fffbdb6d1189ec1f1bd1819ac4c39d5d Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:06:57 -0400 Subject: [PATCH 2/9] add datatemplates req --- docs/sphinx/requirements.in | 1 + docs/sphinx/requirements.txt | 59 +++++++++++++++++++++--------------- 2 files changed, 35 insertions(+), 25 deletions(-) diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in index b1eb21341..5e8a86d75 100644 --- a/docs/sphinx/requirements.in +++ b/docs/sphinx/requirements.in @@ -1 +1,2 @@ rocm-docs-core[api_reference]==1.4.1 +sphinxcontrib.datatemplates==0.11.0 diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt index 5ba5428ea..ca5768e50 100644 --- a/docs/sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -2,13 +2,13 @@ # This file is autogenerated by pip-compile with Python 3.10 # by the following command: # -# pip-compile requirements.in +# pip-compile docs/sphinx/requirements.in # accessible-pygments==0.0.5 # via pydata-sphinx-theme -alabaster==0.7.16 +alabaster==1.0.0 # via sphinx -babel==2.15.0 +babel==2.16.0 # via # pydata-sphinx-theme # sphinx @@ -16,9 +16,9 @@ beautifulsoup4==4.12.3 # via pydata-sphinx-theme breathe==4.35.0 # via rocm-docs-core -certifi==2024.7.4 +certifi==2024.8.30 # via requests -cffi==1.16.0 +cffi==1.17.1 # via # cryptography # pynacl @@ -33,6 +33,8 @@ click-log==0.4.0 # via doxysphinx cryptography==43.0.1 # via pyjwt +defusedxml==0.7.1 + # via sphinxcontrib-datatemplates deprecated==1.2.14 # via pygithub docutils==0.21.2 @@ -41,7 +43,7 @@ docutils==0.21.2 # myst-parser # pydata-sphinx-theme # sphinx -doxysphinx==3.3.9 +doxysphinx==3.3.10 # via rocm-docs-core fastjsonschema==2.20.0 # via rocm-docs-core @@ -49,7 +51,7 @@ gitdb==4.0.11 # via gitpython gitpython==3.1.43 # via rocm-docs-core -idna==3.7 +idna==3.10 # via requests imagesize==1.4.1 # via sphinx @@ -67,13 +69,13 @@ markdown-it-py==3.0.0 # myst-parser markupsafe==2.1.5 # via jinja2 -mdit-py-plugins==0.4.1 +mdit-py-plugins==0.4.2 # via myst-parser mdurl==0.1.2 # via markdown-it-py mpire==2.10.2 # via doxysphinx -myst-parser==3.0.1 +myst-parser==4.0.0 # via rocm-docs-core numpy==1.26.4 # via doxysphinx @@ -87,7 +89,7 @@ pydata-sphinx-theme==0.15.4 # via # rocm-docs-core # sphinx-book-theme -pygithub==2.3.0 +pygithub==2.4.0 # via rocm-docs-core pygments==2.18.0 # via @@ -97,30 +99,31 @@ pygments==2.18.0 # sphinx pyjson5==1.6.6 # via doxysphinx -pyjwt[crypto]==2.8.0 +pyjwt[crypto]==2.9.0 # via pygithub pynacl==1.5.0 # via pygithub -pyparsing==3.1.2 +pyparsing==3.1.4 # via doxysphinx -pyyaml==6.0.1 +pyyaml==6.0.2 # via # myst-parser # rocm-docs-core # sphinx-external-toc + # sphinxcontrib-datatemplates requests==2.32.3 # via # pygithub # sphinx rocm-docs-core[api-reference]==1.4.1 - # via -r requirements.in + # via -r docs/sphinx/requirements.in smmap==5.0.1 # via gitdb snowballstemmer==2.2.0 # via sphinx -soupsieve==2.5 +soupsieve==2.6 # via beautifulsoup4 -sphinx==7.3.7 +sphinx==8.0.2 # via # breathe # myst-parser @@ -131,37 +134,43 @@ sphinx==7.3.7 # sphinx-design # sphinx-external-toc # sphinx-notfound-page + # sphinxcontrib-datatemplates + # sphinxcontrib-runcmd sphinx-book-theme==1.1.3 # via rocm-docs-core sphinx-copybutton==0.5.2 # via rocm-docs-core -sphinx-design==0.6.0 +sphinx-design==0.6.1 # via rocm-docs-core sphinx-external-toc==1.0.1 # via rocm-docs-core -sphinx-notfound-page==1.0.2 +sphinx-notfound-page==1.0.4 # via rocm-docs-core -sphinxcontrib-applehelp==1.0.8 +sphinxcontrib-applehelp==2.0.0 # via sphinx -sphinxcontrib-devhelp==1.0.6 +sphinxcontrib-datatemplates==0.11.0 + # via -r docs/sphinx/requirements.in +sphinxcontrib-devhelp==2.0.0 # via sphinx -sphinxcontrib-htmlhelp==2.0.5 +sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.7 +sphinxcontrib-qthelp==2.0.0 # via sphinx -sphinxcontrib-serializinghtml==1.1.10 +sphinxcontrib-runcmd==0.2.0 + # via sphinxcontrib-datatemplates +sphinxcontrib-serializinghtml==2.0.0 # via sphinx tomli==2.0.1 # via sphinx -tqdm==4.66.4 +tqdm==4.66.5 # via mpire typing-extensions==4.12.2 # via # pydata-sphinx-theme # pygithub -urllib3==2.2.2 +urllib3==2.2.3 # via # pygithub # requests From e2f4e41372f8bb1cf9caacba5a0f890b9bbba1b9 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:07:23 -0400 Subject: [PATCH 3/9] inject omnitrace version into Omnitrace installer download cmd --- docs/install/quick-start.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/install/quick-start.rst b/docs/install/quick-start.rst index 90c8c1b48..0c130563c 100644 --- a/docs/install/quick-start.rst +++ b/docs/install/quick-start.rst @@ -6,16 +6,18 @@ Omnitrace quick start ************************************* -To install Omnitrace, download the `Omnitrace installer `_ -and specify ``--prefix ``. The script attempts to auto-detect -the appropriate OS distribution and version. To include AMD ROCm Software support, -specify ``--rocm X.Y``, where ``X`` is the ROCm major -version and ``Y`` is the ROCm minor version, for example, ``--rocm 6.2``. +.. datatemplate:nodata:: -.. code-block:: shell + To install Omnitrace, download the `Omnitrace installer `_ + and specify ``--prefix ``. The script attempts to auto-detect + the appropriate OS distribution and version. To include AMD ROCm Software support, + specify ``--rocm X.Y``, where ``X`` is the ROCm major + version and ``Y`` is the ROCm minor version, for example, ``--rocm 6.2``. - wget https://github.com/ROCm/omnitrace/releases/latest/download/omnitrace-install.py - python3 ./omnitrace-install.py --prefix /opt/omnitrace --rocm 6.2 + .. code-block:: shell + + wget https://github.com/ROCm/omnitrace/releases/{{ config.version }}/download/omnitrace-install.py + python3 ./omnitrace-install.py --prefix /opt/omnitrace --rocm 6.2 This script supports installation on Ubuntu, OpenSUSE, Red Hat, Debian, CentOS, and Fedora. If the target OS is compatible with one of the operating system versions listed in From b3894a53b0bfec261b0e0321a990ec3d94582fef Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:13:55 -0400 Subject: [PATCH 4/9] bump rocm-docs-core to 1.8.1 to fix build error --- docs/sphinx/requirements.in | 2 +- docs/sphinx/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/requirements.in b/docs/sphinx/requirements.in index 5e8a86d75..5230f25a0 100644 --- a/docs/sphinx/requirements.in +++ b/docs/sphinx/requirements.in @@ -1,2 +1,2 @@ -rocm-docs-core[api_reference]==1.4.1 +rocm-docs-core[api_reference]==1.8.1 sphinxcontrib.datatemplates==0.11.0 diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt index ca5768e50..a2a18371d 100644 --- a/docs/sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -115,7 +115,7 @@ requests==2.32.3 # via # pygithub # sphinx -rocm-docs-core[api-reference]==1.4.1 +rocm-docs-core[api-reference]==1.8.1 # via -r docs/sphinx/requirements.in smmap==5.0.1 # via gitdb From dbb1871d5269de20a16777faf5a7b974f5ef6281 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:14:46 -0400 Subject: [PATCH 5/9] fix doxygen project name --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index f350e4f18..84936a269 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,7 +52,7 @@ doxygen_root = "doxygen" doxysphinx_enabled = True doxygen_project = { - "name": "ROCm Docs Core Test Project - Extension", + "name": "Omnitrace API", "path": "doxygen/xml", } external_projects_remote_repository = "" From ec92a25da17df4083f36a0c5c7e029886c4c973c Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:20:31 -0400 Subject: [PATCH 6/9] fix url template remove no intersphinx fix typo --- docs/conf.py | 3 +-- docs/install/quick-start.rst | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 84936a269..3173fabc9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,7 +35,7 @@ version_number = match[1] # project info -project = "Omniperf" +project = "Omnitrace" author = "Advanced Micro Devices, Inc." copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved." version = version_number @@ -55,4 +55,3 @@ "name": "Omnitrace API", "path": "doxygen/xml", } -external_projects_remote_repository = "" diff --git a/docs/install/quick-start.rst b/docs/install/quick-start.rst index 0c130563c..abb5da938 100644 --- a/docs/install/quick-start.rst +++ b/docs/install/quick-start.rst @@ -8,7 +8,7 @@ Omnitrace quick start .. datatemplate:nodata:: - To install Omnitrace, download the `Omnitrace installer `_ + To install Omnitrace, download the `Omnitrace installer `_ and specify ``--prefix ``. The script attempts to auto-detect the appropriate OS distribution and version. To include AMD ROCm Software support, specify ``--rocm X.Y``, where ``X`` is the ROCm major From 305c4db605d821a9755927ca0af575c35251901d Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:31:37 -0400 Subject: [PATCH 7/9] fix sphinx heading warnings --- docs/reference/development-guide.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/development-guide.rst b/docs/reference/development-guide.rst index d04338ede..d2140199c 100644 --- a/docs/reference/development-guide.rst +++ b/docs/reference/development-guide.rst @@ -25,7 +25,7 @@ The ``main`` routine of ``omnitrace-avail`` has three important sections: * Printing hardware counters omnitrace-sample: `source/bin/omnitrace-sample `_ -------------------------------------------------------------------------------------------------------------------------------- +---------------------------------------------------------------------------------------------------------------------------------- * Requires a command-line format of ``omnitrace-sample -- `` * Translates command-line options into environment variables @@ -33,7 +33,7 @@ omnitrace-sample: `source/bin/omnitrace-sample `` and a modified environment omnitrace-casual: `source/bin/omnitrace-causal `_ -------------------------------------------------------------------------------------------------------------------------------- +---------------------------------------------------------------------------------------------------------------------------------- When there is exactly one causal profiling configuration variant (which enables debugging), ``omnitrace-casual`` has a nearly identical design to ``omnitrace-sample`` @@ -46,7 +46,7 @@ the following actions take place for each variant: * the parent process waits for the child process to finish omnitrace-instrument: `source/bin/omnitrace-instrument `_ -------------------------------------------------------------------------------------------------------------------------------------------- +---------------------------------------------------------------------------------------------------------------------------------------------- * Requires a command-line format of ``omnitrace-instrument -- `` * Allows the user to provide options specifying whether to perform runtime instrumentation, use binary rewrite, or @@ -409,4 +409,4 @@ to this sequence: Eventually, the goal is to migrate all subsets of data collection which currently support more rudimentary models of time window constraints, such as process sampling and causal profiling, -to this model. \ No newline at end of file +to this model. From e14d04e8ed57879c656e4485a5bfbc1bf4aebd92 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:31:49 -0400 Subject: [PATCH 8/9] actually fix url --- docs/install/quick-start.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/quick-start.rst b/docs/install/quick-start.rst index abb5da938..2964bdcdb 100644 --- a/docs/install/quick-start.rst +++ b/docs/install/quick-start.rst @@ -16,7 +16,7 @@ Omnitrace quick start .. code-block:: shell - wget https://github.com/ROCm/omnitrace/releases/{{ config.version }}/download/omnitrace-install.py + wget https://github.com/ROCm/omnitrace/releases/download/v{{ config.version }}/omnitrace-install.py python3 ./omnitrace-install.py --prefix /opt/omnitrace --rocm 6.2 This script supports installation on Ubuntu, OpenSUSE, Red Hat, Debian, CentOS, and Fedora. From 6943482b18f225ffd7d2fe7b93c3427daf3c5be4 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Mon, 23 Sep 2024 18:42:24 -0400 Subject: [PATCH 9/9] add version template to install.rst --- docs/install/install.rst | 66 +++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/install/install.rst b/docs/install/install.rst index f0ee1662c..e89f7a978 100644 --- a/docs/install/install.rst +++ b/docs/install/install.rst @@ -69,45 +69,47 @@ might be more portable. Installing Omnitrace from binary distributions ================================================ -Every Omnitrace release provides binary installer scripts of the form: +.. datatemplate:nodata:: -.. code-block:: shell + Every Omnitrace release provides binary installer scripts of the form: - omnitrace-{VERSION}-{OS_DISTRIB}-{OS_VERSION}[-ROCm-{ROCM_VERSION}[-{EXTRA}]].sh + .. code-block:: shell -For example, + omnitrace-{{ config.version }}-{OS_DISTRIB}-{OS_VERSION}[-ROCm-{ROCM_VERSION}[-{EXTRA}]].sh -.. code-block:: shell + For example, - omnitrace-1.0.0-ubuntu-18.04-OMPT-PAPI-Python3.sh - omnitrace-1.0.0-ubuntu-18.04-ROCm-405000-OMPT-PAPI-Python3.sh - ... - omnitrace-1.0.0-ubuntu-20.04-ROCm-50000-OMPT-PAPI-Python3.sh + .. code-block:: shell -Any of the ``EXTRA`` fields with a CMake build option -(for example, PAPI, as referenced in a following section) or -with no link requirements (such as OMPT) have -self-contained support for these packages. + omnitrace-{{ config.version }}-ubuntu-18.04-OMPT-PAPI-Python3.sh + omnitrace-{{ config.version }}-ubuntu-18.04-ROCm-405000-OMPT-PAPI-Python3.sh + ... + omnitrace-{{ config.version }}-ubuntu-20.04-ROCm-50000-OMPT-PAPI-Python3.sh -To install Omnitrace using a binary installer script, follow these steps: + Any of the ``EXTRA`` fields with a CMake build option + (for example, PAPI, as referenced in a following section) or + with no link requirements (such as OMPT) have + self-contained support for these packages. -#. Download the appropriate binary distribution + To install Omnitrace using a binary installer script, follow these steps: - .. code-block:: shell + #. Download the appropriate binary distribution - wget https://github.com/ROCm/omnitrace/releases/download/v/