Docs: refactor and integrate into ROCm docs portal (#362)

* pip-compile docs/requirements.txt Signed-off-by: Peter Jun Park <peter.park@amd.com> Add Sphinx docs config Signed-off-by: Peter Jun Park <peter.park@amd.com> Add Sphinx config Signed-off-by: Peter Jun Park <peter.park@amd.com> Update docs build config Signed-off-by: Peter Jun Park <peter.park@amd.com> * style(conf.py): Apply black formatting to docs/conf.py Signed-off-by: Sam Wu <22262939+samjwu@users.noreply.github.com> * Update docs requirements Signed-off-by: Peter Jun Park <peter.park@amd.com> Update to rocm-docs-core 1.3.0 Signed-off-by: Peter Jun Park <peter.park@amd.com> Update docs requirements Signed-off-by: Peter Jun Park <peter.park@amd.com> pip-compile requirements Signed-off-by: Peter Jun Park <peter.park@amd.com> bump rocm-docs-core to 1.5.0 bump rocm-docs-core to 1.4.1 Signed-off-by: Peter Jun Park <peter.park@amd.com> * Add dependabot.yml and update CODEOWNERS Signed-off-by: Peter Jun Park <peter.park@amd.com> Update toc and conf Signed-off-by: Peter Jun Park <peter.park@amd.com> update dependabot * Port docs to rocm-docs standard Signed-off-by: Peter Jun Park <peter.park@amd.com> Add toc and Diataxis cards Signed-off-by: Peter Jun Park <peter.park@amd.com> Add basic file structure Signed-off-by: Peter Jun Park <peter.park@amd.com> add glossary Signed-off-by: Peter Jun Park <peter.park@amd.com> add includes Signed-off-by: Peter Jun Park <peter.park@amd.com> Add license.rst Signed-off-by: Peter Jun Park <peter.park@amd.com> add compatible hw Signed-off-by: Peter Jun Park <peter.park@amd.com> fix spelling and license Signed-off-by: Peter Jun Park <peter.park@amd.com> clean up index Signed-off-by: Peter Jun Park <peter.park@amd.com> clean up installation guides Signed-off-by: Peter Jun Park <peter.park@amd.com> add basic usage (quickstart) Signed-off-by: Peter Jun Park <peter.park@amd.com> add ref to global options update toc Signed-off-by: Peter Jun Park <peter.park@amd.com> modularize modes and global options Signed-off-by: Peter Jun Park <peter.park@amd.com> add profile mode Signed-off-by: Peter Jun Park <peter.park@amd.com> fixes Signed-off-by: Peter Jun Park <peter.park@amd.com> reorg and clean up Signed-off-by: Peter Jun Park <peter.park@amd.com> add dynamic omniperf version number in installation guide Signed-off-by: Peter Jun Park <peter.park@amd.com> add datatemplate more reorg Signed-off-by: Peter Jun Park <peter.park@amd.com> clean up Signed-off-by: Peter Jun Park <peter.park@amd.com> reorg images move profile mode reorg reorg reorg more fix formatting fix headings ref anchor mi2xx note add extlinks add extlinks Signed-off-by: Peter Jun Park <peter.park@amd.com> black format fix formatting, anchors Signed-off-by: Peter Jun Park <peter.park@amd.com> reorg fix words and formatting Signed-off-by: Peter Jun Park <peter.park@amd.com> formatting Signed-off-by: Peter Jun Park <peter.park@amd.com> same reorg format fix formatting fix toc Signed-off-by: Peter Jun Park <peter.park@amd.com> format * impr internal linking and fix sphinx warnings Signed-off-by: Peter Jun Park <peter.park@amd.com> * add spellcheck/linting from rocm-docs-core Signed-off-by: Peter Jun Park <peter.park@amd.com> fix rst directives satisfy spellcheck fix more spelling rm unused files fix spelling and update wordlist * bump rocm-docs-core to 1.6.0 Signed-off-by: Peter Jun Park <peter.park@amd.com> * add fixes from @skyreflectedinmirrors and @lpaoletti Signed-off-by: Peter Jun Park <peter.park@amd.com> add references to toc Signed-off-by: Peter Jun Park <peter.park@amd.com> add more fixes Signed-off-by: Peter Jun Park <peter.park@amd.com> * add package manager install section Signed-off-by: Peter Jun Park <peter.park@amd.com> * add fixes Signed-off-by: Peter Jun Park <peter.park@amd.com> add metadata and fixes Signed-off-by: Peter Jun Park <peter.park@amd.com> add fixes bump to 1.6.1 more fixes fix fmt in profiling examples Signed-off-by: Peter Jun Park <peter.park@amd.com> add missing mem type table Signed-off-by: Peter Jun Park <peter.park@amd.com> fix formatting fmt * add custom css Signed-off-by: Peter Jun Park <peter.park@amd.com> fix css fs * make images/figs click-to-expand Signed-off-by: Peter Jun Park <peter.park@amd.com> add missed image update fix link * update documentation link in README Signed-off-by: Peter Jun Park <peter.park@amd.com> * formatting fixes Signed-off-by: Peter Jun Park <peter.park@amd.com> more formatting * fix heading Signed-off-by: Peter Jun Park <peter.park@amd.com> * move archived docs Signed-off-by: Peter Jun Park <peter.park@amd.com> * exclude archived docs from docs build Signed-off-by: Peter Jun Park <peter.park@amd.com> * update archived docs workflow Signed-off-by: Peter Jun Park <peter.park@amd.com> move files update archived docs workflow Signed-off-by: Peter Jun Park <peter.park@amd.com> fix version number clean up workflow workflow test workflow test another workflow test * rm docs linting Signed-off-by: Peter Jun Park <peter.park@amd.com> * Apply cmake-format suggested changes Signed-off-by: Sam Wu <22262939+samjwu@users.noreply.github.com> * Apply cmake-format Signed-off-by: Sam Wu <22262939+samjwu@users.noreply.github.com> --------- Signed-off-by: Peter Jun Park <peter.park@amd.com> Signed-off-by: Sam Wu <22262939+samjwu@users.noreply.github.com> Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com> [ROCm/rocprofiler-compute commit: a0dc485ceb]
2024-08-09 09:46:42 -04:00
@@ -1,6 +1,7 @@
 * @koomie @coleramos425

 # Documentation files
-docs/* @ROCm/rocm-documentation
+docs/ @ROCm/rocm-documentation
 *.md @ROCm/rocm-documentation
 *.rst @ROCm/rocm-documentation
+.readthedocs.yaml @ROCm/rocm-documentation
@@ -0,0 +1,18 @@
+# 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"
+    target-branch: "dev"
+    labels:
+      - "documentation"
+      - "dependencies"
+    reviewers:
+      - "samjwu"
@@ -4,10 +4,9 @@ on:
  push:
    branches: ["main"]
    paths:
-      - 'src/docs'
-      - 'src/archive/docs-1.x'
+      - 'docs/archive/docs-2.x/**'
+      - 'docs/archive/docs-1.x/**'
      - '.github/workflows/docs.yml'
-      - 'VERSION'

  workflow_dispatch:

@@ -31,24 +30,24 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Additional python packages
-        run: pip3 install -r requirements-doc.txt
+        run: pip3 install -r docs/archive/requirements-doc.txt
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Build 1.x docs
        run: |
-          cd src/archive/docs-1.x
+          cd docs/archive/docs-1.x
          make html	
-      - name: Build current docs
+      - name: Build 2.x docs
        run: |
-          cd src/docs
+          cd docs/archive/docs-2.x
          make html
      - name: Relocate 1.x docs
        run: |
-          mv src/archive/docs-1.x/_build/html src/docs/_build/html/1.x
+          mv docs/archive/docs-1.x/_build/html docs/archive/_build/html/1.x
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
-          path: ./src/docs/_build/html
+          path: ./docs/archive/_build/html

  # Deployment job
  deploy:
@@ -19,3 +19,8 @@ VERSION.sha

 # temp files
 /tests/Testing
+
+# documentation artifacts
+/_build
+_toc.yml
+
@@ -0,0 +1,13 @@
+# 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
@@ -189,46 +189,51 @@ message(STATUS "Pytest CPU threadcount: ${PYTEST_NUMPROCS}")

 add_test(
    NAME test_profile_kernel_execution
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m kernel_execution --junitxml=tests/test_profile_kernel_execution.xml
-            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -m kernel_execution
+        --junitxml=tests/test_profile_kernel_execution.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

 add_test(
    NAME test_profile_ipblocks
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m block --junitxml=tests/test_profile_blocks.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -m block --junitxml=tests/test_profile_blocks.xml
+        ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 set_property(TEST test_profile_ipblocks PROPERTY COST 11)

 add_test(
    NAME test_profile_dispatch
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m dispatch --junitxml=tests/test_profile_dispatch.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -m dispatch
+        --junitxml=tests/test_profile_dispatch.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
 set_property(TEST test_profile_ipblocks PROPERTY COST 5)

 add_test(
    NAME test_profile_mem
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m mem --junitxml=tests/test_profile_mem.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m mem --junitxml=tests/test_profile_mem.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

 add_test(
    NAME test_profile_join
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m join --junitxml=tests/test_profile_join.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m join --junitxml=tests/test_profile_join.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

 add_test(
    NAME test_profile_sort
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m sort --junitxml=tests/test_profile_sort.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m sort --junitxml=tests/test_profile_sort.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

 add_test(
    NAME test_profile_misc
-    COMMAND ${Python3_EXECUTABLE} -m pytest -m misc --junitxml=tests/test_profile_misc.xml ${COV_OPTION}
-            ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
+    COMMAND ${Python3_EXECUTABLE} -m pytest -m misc --junitxml=tests/test_profile_misc.xml
+            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_profile_general.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

 set_tests_properties(
@@ -247,8 +252,10 @@ set_tests_properties(

 add_test(
    NAME test_analyze_commands
-    COMMAND ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS} --junitxml=tests/test_analyze_commands.xml
-            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_analyze_commands.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS}
+        --junitxml=tests/test_analyze_commands.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_analyze_commands.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

 # ---------------------------
@@ -257,8 +264,10 @@ add_test(

 add_test(
    NAME test_analyze_workloads
-    COMMAND ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS} --junitxml=tests/test_analyze_workloads.xml
-            ${COV_OPTION} ${PROJECT_SOURCE_DIR}/tests/test_analyze_workloads.py
+    COMMAND
+        ${Python3_EXECUTABLE} -m pytest -n ${PYTEST_NUMPROCS}
+        --junitxml=tests/test_analyze_workloads.xml ${COV_OPTION}
+        ${PROJECT_SOURCE_DIR}/tests/test_analyze_workloads.py
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

 # ---------
@@ -4,17 +4,17 @@
 [![Docs](https://github.com/ROCm/omniperf/actions/workflows/docs.yml/badge.svg)](https://rocm.github.io/omniperf/)
 [![DOI](https://zenodo.org/badge/561919887.svg)](https://zenodo.org/badge/latestdoi/561919887)

-
 # Omniperf

 ## General
+
 Omniperf is a system performance profiling tool for machine
 learning/HPC workloads running on AMD MI GPUs. The tool presently
 targets usage on MI100, MI200, and MI300 accelerators.

 * For more information on available features, installation steps, and
 workload profiling and analysis, please refer to the online
-[documentation](https://rocm.github.io/omniperf).
+[documentation](https://rocm.docs.amd.com/projects/omniperf/en/latest/).

 * Omniperf is an AMD open source research project and is not supported
 as part of the ROCm software stack. We welcome contributions and
@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = _build
+BUILDDIR      = ../_build

 # Put it first so that "make" without argument is like "make help".
 help:
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -0,0 +1 @@
+2.0.1
@@ -20,8 +20,8 @@ sys.path.insert(0, os.path.abspath(".."))

 repo_version = "unknown"
 # Determine short version by file in repo
-if os.path.isfile("../../VERSION"):
-    with open("../../VERSION") as f:
+if os.path.isfile("./VERSION"):
+    with open("./VERSION") as f:
        repo_version = f.readline().strip()