Docs: refactor and integrate into ROCm docs portal

.github/CODEOWNERS

@@ -4,3 +4,4 @@
 docs/* @ROCm/rocm-documentation
 *.md @ROCm/rocm-documentation
 *.rst @ROCm/rocm-documentation
+.readthedocs.yaml @ROCm/rocm-documentation

.github/dependabot.yml

@@ -9,3 +9,14 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
+
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/docs/sphinx" # Location of package manifests
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "daily"
+    labels:
+      - "documentation"
+      - "dependencies"
+    reviewers:
+      - "samjwu"

.github/workflows/lint-docs.yml

@@ -0,0 +1,20 @@
+name: Lint Documentation
+
+on:
+  push:
+    branches: 
+    - main
+    - 'docs/*'
+    - 'release/*'
+    - 'roc**'
+  pull_request:
+    branches: 
+    - main
+    - 'docs/*'
+    - 'release/*'
+    - 'roc**'
+
+jobs:
+  call-workflow-passing-data:
+    name: Documentation
+    uses: ROCm/rocm-docs-core/.github/workflows/linting.yml@develop

.gitignore

@@ -37,6 +37,10 @@
 # Python cache files
 *.pyc
 
+# Documentation artifacts
+/_build
+_toc.yml
+
 /build*
 /.vscode
 /.cache

.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.10"
+
+python:
+  install:
+  - requirements: docs/sphinx/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py
+
+formats: []

docs/conf.py

@@ -0,0 +1,53 @@
+# MIT License
+
+# Copyright (c) 2023 - 2024 Advanced Micro Devices, Inc. All rights reserved.
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# 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 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]
+
+project = "omnitrace"
+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"
+
+docs_core = ROCmDocs(left_nav_title)
+docs_core.setup()
+
+
+for sphinx_var in ROCmDocs.SPHINX_VARS:
+    globals()[sphinx_var] = getattr(docs_core, sphinx_var)

docs/index.rst

@@ -0,0 +1,7 @@
+.. meta::
+   :description: Omniperf documentation and reference
+   :keywords: Omniperf, ROCm, profiler, tool, Instinct, accelerator, AMD
+
+***********************
+Omnitrace documentation
+***********************

docs/sphinx/_toc.yml.in

@@ -0,0 +1,9 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+defaults:
+  numbered: False
+  maxdepth: 6
+root: index
+subtrees:
+  - entries:
+    - file: what-is-omnitrace.rst

docs/sphinx/requirements.in

@@ -0,0 +1 @@
+rocm-docs-core==1.4.0

docs/sphinx/requirements.txt

@@ -0,0 +1,147 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile docs/sphinx/requirements.in
+#
+accessible-pygments==0.0.5
+    # via pydata-sphinx-theme
+alabaster==0.7.16
+    # via sphinx
+babel==2.15.0
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+beautifulsoup4==4.12.3
+    # via pydata-sphinx-theme
+breathe==4.35.0
+    # via rocm-docs-core
+certifi==2024.6.2
+    # via requests
+cffi==1.16.0
+    # via
+    #   cryptography
+    #   pynacl
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via sphinx-external-toc
+cryptography==42.0.8
+    # via pyjwt
+deprecated==1.2.14
+    # via pygithub
+docutils==0.21.2
+    # via
+    #   breathe
+    #   myst-parser
+    #   pydata-sphinx-theme
+    #   sphinx
+fastjsonschema==2.19.1
+    # via rocm-docs-core
+gitdb==4.0.11
+    # via gitpython
+gitpython==3.1.43
+    # via rocm-docs-core
+idna==3.7
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.4
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.5
+    # via jinja2
+mdit-py-plugins==0.4.1
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==3.0.1
+    # via rocm-docs-core
+packaging==24.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+pycparser==2.22
+    # via cffi
+pydata-sphinx-theme==0.15.3
+    # via
+    #   rocm-docs-core
+    #   sphinx-book-theme
+pygithub==2.3.0
+    # via rocm-docs-core
+pygments==2.18.0
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
+pyjwt[crypto]==2.8.0
+    # via pygithub
+pynacl==1.5.0
+    # via pygithub
+pyyaml==6.0.1
+    # via
+    #   myst-parser
+    #   rocm-docs-core
+    #   sphinx-external-toc
+requests==2.32.3
+    # via
+    #   pygithub
+    #   sphinx
+rocm-docs-core==1.4.0
+    # via -r docs/sphinx/requirements.in
+smmap==5.0.1
+    # via gitdb
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.5
+    # via beautifulsoup4
+sphinx==7.3.7
+    # 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.1.2
+    # via rocm-docs-core
+sphinx-copybutton==0.5.2
+    # via rocm-docs-core
+sphinx-design==0.6.0
+    # via rocm-docs-core
+sphinx-external-toc==1.0.1
+    # via rocm-docs-core
+sphinx-notfound-page==1.0.2
+    # via rocm-docs-core
+sphinxcontrib-applehelp==1.0.8
+    # via sphinx
+sphinxcontrib-devhelp==1.0.6
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.5
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.7
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.10
+    # via sphinx
+tomli==2.0.1
+    # via sphinx
+typing-extensions==4.12.2
+    # via
+    #   pydata-sphinx-theme
+    #   pygithub
+urllib3==2.2.1
+    # via
+    #   pygithub
+    #   requests
+wrapt==1.16.0
+    # via deprecated

docs/what-is-omnitrace.rst

@@ -0,0 +1,26 @@
+******************
+What is Omnitrace?
+******************
+
+Omnitrace is an AMD open source research project and is not supported as part
+of the ROCm software stack.
+
+Omnitrace is designed for both high-level profiling and comprehensive tracing
+of applications running on the CPU or the CPU+GPU via dynamic binary
+instrumentation, call-stack sampling, and various other means for determining
+currently executing function and line information.
+
+Visualization of the comprehensive omnitrace results can be viewed in any modern
+web browser by visiting [ui.perfetto.dev](https://ui.perfetto.dev/) and loading
+the perfetto output (`.proto` files) produced by omnitrace.
+
+Aggregated high-level results are available in text files for human consumption and JSON files for programmatic analysis.
+The JSON output files are compatible with the python package [hatchet](https://github.com/hatchet/hatchet) which converts
+the performance data into pandas dataframes and facilitate multi-run comparisons, filtering, visualization in Jupyter notebooks,
+and much more.
+
+ Omnitrace has two distinct configuration steps when instrumenting:
+
+1. Configuring which functions and modules are instrumented in the target binaries (i.e. executable and/or libraries)
+2. Configuring what the instrumentation does happens when the instrumented binaries are executed
+