From 301220e79d1d325588f5a53126ebb7f5b1617ab3 Mon Sep 17 00:00:00 2001 From: Peter Park Date: Wed, 31 Jul 2024 10:42:27 -0400 Subject: [PATCH] Docs: refactor and integrate into ROCm docs portal (#362) * pip-compile docs/requirements.txt Signed-off-by: Peter Jun Park Add Sphinx docs config Signed-off-by: Peter Jun Park Add Sphinx config Signed-off-by: Peter Jun Park Update docs build config Signed-off-by: Peter Jun Park * 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 Update to rocm-docs-core 1.3.0 Signed-off-by: Peter Jun Park Update docs requirements Signed-off-by: Peter Jun Park pip-compile requirements Signed-off-by: Peter Jun Park bump rocm-docs-core to 1.5.0 bump rocm-docs-core to 1.4.1 Signed-off-by: Peter Jun Park * Add dependabot.yml and update CODEOWNERS Signed-off-by: Peter Jun Park Update toc and conf Signed-off-by: Peter Jun Park update dependabot * Port docs to rocm-docs standard Signed-off-by: Peter Jun Park Add toc and Diataxis cards Signed-off-by: Peter Jun Park Add basic file structure Signed-off-by: Peter Jun Park add glossary Signed-off-by: Peter Jun Park add includes Signed-off-by: Peter Jun Park Add license.rst Signed-off-by: Peter Jun Park add compatible hw Signed-off-by: Peter Jun Park fix spelling and license Signed-off-by: Peter Jun Park clean up index Signed-off-by: Peter Jun Park clean up installation guides Signed-off-by: Peter Jun Park add basic usage (quickstart) Signed-off-by: Peter Jun Park add ref to global options update toc Signed-off-by: Peter Jun Park modularize modes and global options Signed-off-by: Peter Jun Park add profile mode Signed-off-by: Peter Jun Park fixes Signed-off-by: Peter Jun Park reorg and clean up Signed-off-by: Peter Jun Park add dynamic omniperf version number in installation guide Signed-off-by: Peter Jun Park add datatemplate more reorg Signed-off-by: Peter Jun Park clean up Signed-off-by: Peter Jun Park 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 black format fix formatting, anchors Signed-off-by: Peter Jun Park reorg fix words and formatting Signed-off-by: Peter Jun Park formatting Signed-off-by: Peter Jun Park same reorg format fix formatting fix toc Signed-off-by: Peter Jun Park format * impr internal linking and fix sphinx warnings Signed-off-by: Peter Jun Park * add spellcheck/linting from rocm-docs-core Signed-off-by: Peter Jun Park 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 * add fixes from @skyreflectedinmirrors and @lpaoletti Signed-off-by: Peter Jun Park add references to toc Signed-off-by: Peter Jun Park add more fixes Signed-off-by: Peter Jun Park * add package manager install section Signed-off-by: Peter Jun Park * add fixes Signed-off-by: Peter Jun Park add metadata and fixes Signed-off-by: Peter Jun Park add fixes bump to 1.6.1 more fixes fix fmt in profiling examples Signed-off-by: Peter Jun Park add missing mem type table Signed-off-by: Peter Jun Park fix formatting fmt * add custom css Signed-off-by: Peter Jun Park fix css fs * make images/figs click-to-expand Signed-off-by: Peter Jun Park add missed image update fix link * update documentation link in README Signed-off-by: Peter Jun Park * formatting fixes Signed-off-by: Peter Jun Park more formatting * fix heading Signed-off-by: Peter Jun Park * move archived docs Signed-off-by: Peter Jun Park * exclude archived docs from docs build Signed-off-by: Peter Jun Park * update archived docs workflow Signed-off-by: Peter Jun Park move files update archived docs workflow Signed-off-by: Peter Jun Park fix version number clean up workflow workflow test workflow test another workflow test * rm docs linting Signed-off-by: Peter Jun Park * 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 Signed-off-by: Sam Wu <22262939+samjwu@users.noreply.github.com> Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com> Signed-off-by: xuchen-amd --- .github/workflows/dependabot.yml | 2 +- .github/workflows/docs.yml | 5 +-- docs/conf.py | 2 +- docs/how-to/analyze/cli.rst | 2 +- docs/how-to/profile/mode.rst | 2 +- docs/install/core-install.rst | 35 +++---------------- docs/sphinx/static/css/o_custom.css | 22 ++++++++++++ .../includes/infinity-fabric-transactions.rst | 2 +- .../includes/occupancy-limiters-example.rst | 2 +- .../vector-memory-operation-counting.rst | 2 +- docs/tutorial/profiling-by-example.rst | 2 +- 11 files changed, 38 insertions(+), 40 deletions(-) diff --git a/.github/workflows/dependabot.yml b/.github/workflows/dependabot.yml index 90f2d871e..48d6228ba 100644 --- a/.github/workflows/dependabot.yml +++ b/.github/workflows/dependabot.yml @@ -10,7 +10,7 @@ updates: open-pull-requests-limit: 10 schedule: interval: "daily" - target-branch: "amd-staging" + target-branch: "dev" labels: - "documentation" - "dependencies" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9b6e57bdb..e61f66e98 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,6 +4,8 @@ on: push: branches: [ amd-mainline ] paths: + - 'docs/archive/docs-2.x/**' + - 'docs/archive/docs-1.x/**' - 'docs/archive/docs-2.x/**' - 'docs/archive/docs-1.x/**' - '.github/workflows/docs.yml' @@ -36,8 +38,7 @@ jobs: - name: Build 1.x docs run: | cd docs/archive/docs-1.x - cd docs/archive/docs-1.x - make html + make html - name: Build 2.x docs run: | cd docs/archive/docs-2.x diff --git a/docs/conf.py b/docs/conf.py index f74f95ecd..b38ce2e5c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,7 +55,7 @@ # frequently used external resources extlinks = { - "dev-sample": ("https://github.com/ROCm/omniperf/blob/amd-mainline/sample/%s", "%s"), + "dev-sample": ("https://github.com/ROCm/omniperf/blob/dev/sample/%s", "%s"), "prod-page": ( "https://www.amd.com/en/products/accelerators/instinct/%s.html", "%s", diff --git a/docs/how-to/analyze/cli.rst b/docs/how-to/analyze/cli.rst index 82185cd41..f76e3970f 100644 --- a/docs/how-to/analyze/cli.rst +++ b/docs/how-to/analyze/cli.rst @@ -186,7 +186,7 @@ Walkthrough 3. Choose your own customized subset of metrics with the ``-b`` (or ``--block``) option. Or, build your own configuration following - `config_template `_. + `config_template `_. The following snippet shows how to generate a report containing only metric 2 (:doc:`System Speed-of-Light `). diff --git a/docs/how-to/profile/mode.rst b/docs/how-to/profile/mode.rst index 5bc0ad6a7..de23a801b 100644 --- a/docs/how-to/profile/mode.rst +++ b/docs/how-to/profile/mode.rst @@ -38,7 +38,7 @@ Run ``omniperf profile -h`` for more details. See Profiling example ----------------- -The ``__ repository +The ``__ repository includes source code for a sample GPU compute workload, ``vcopy.cpp``. A copy of this file is available in the ``share/sample`` subdirectory after a normal Omniperf installation, or via the ``$OMNIPERF_SHARE/sample`` directory when diff --git a/docs/install/core-install.rst b/docs/install/core-install.rst index f33b97622..1d28b07b5 100644 --- a/docs/install/core-install.rst +++ b/docs/install/core-install.rst @@ -32,7 +32,7 @@ right for you. :width: 800 .. _core-install: - + Core installation ================= @@ -44,12 +44,6 @@ installation. * CMake ``>= 3.19`` * ROCm ``>= 5.7.1`` -.. note:: - - Omniperf will use the first version of ``Python3`` found in your system's - ``PATH``. If the default version of Python3 is older than 3.8, you may need to - update your system's ``PATH`` to point to a newer version of Python3. - Omniperf depends on a number of Python packages documented in the top-level ``requirements.txt`` file. Install these *before* configuring Omniperf. @@ -72,16 +66,6 @@ following steps illustrate how to install the necessary Python dependencies using `pip `_ and Omniperf into a shared location controlled by the ``INSTALL_DIR`` environment variable. -.. tip:: - - To always run Omniperf with a particular version of python, you can create a - bash alias. For example, to run Omniperf with Python 3.10, you can run the - following command: - - .. code-block:: shell - - alias omniperf-mypython="/usr/bin/python3.10 /opt/rocm/bin/omniperf" - .. _core-install-cmake-vars: Configuration variables @@ -142,7 +126,7 @@ Install from source cd build cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{{ config.version }} \ -DPYTHON_DEPS=${INSTALL_DIR}/python-libs \ - -DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles/omniperf .. + -DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles .. # install make install @@ -224,30 +208,21 @@ software stack. .. code-block:: shell $ sudo apt install omniperf - # Include omniperf in your system PATH - $ sudo update-alternatives --install /usr/bin/omniperf omniperf /opt/rocm/bin/omniperf 0 - # Install Python dependencies - $ python3 -m pip install -r /opt/rocm/libexec/omniperf/requirements.txt + $ pip install -r /opt/rocm/libexec/omniperf/requirements.txt .. tab-item:: Red Hat Enterprise Linux .. code-block:: shell $ sudo dnf install omniperf - # Include omniperf in your system PATH - $ sudo update-alternatives --install /usr/bin/omniperf omniperf /opt/rocm/bin/omniperf 0 - # Install Python dependencies - $ python3 -m pip install -r /opt/rocm/libexec/omniperf/requirements.txt + $ pip install -r /opt/rocm/libexec/omniperf/requirements.txt .. tab-item:: SUSE Linux Enterprise Server .. code-block:: shell $ sudo zypper install omniperf - # Include omniperf in your system PATH - $ sudo update-alternatives --install /usr/bin/omniperf omniperf /opt/rocm/bin/omniperf 0 - # Install Python dependencies - $ python3 -m pip install -r /opt/rocm/libexec/omniperf/requirements.txt + $ pip install -r /opt/rocm/libexec/omniperf/requirements.txt .. _core-install-rocprof-var: diff --git a/docs/sphinx/static/css/o_custom.css b/docs/sphinx/static/css/o_custom.css index b4fe010b5..a6cbe5718 100644 --- a/docs/sphinx/static/css/o_custom.css +++ b/docs/sphinx/static/css/o_custom.css @@ -1,8 +1,30 @@ +:root { + --amd-teal-500: #00C2DE; + --amd-teal-750: #00788E; +} + /* Override PyData Sphinx Theme default colors */ html[data-theme='light'] { + --pst-color-primary: var(--amd-teal-750); + --pst-color-primary-bg: var(--amd-teal-500); --pst-color-table-row-hover-bg: #E2E8F0; } html[data-theme='dark'] { + --pst-color-primary: var(--amd-teal-500); + --pst-color-primary-bg: var(--amd-teal-750); --pst-color-table-row-hover-bg: #1E293B; } + +html[data-theme='light'], +html[data-theme='dark'] { + --pst-color-link: var(--pst-color-primary); +} + +a svg { + color: var(--pst-color-text-base); +} + +a svg:hover { + color: var(--pst-color-link-hover); +} diff --git a/docs/tutorial/includes/infinity-fabric-transactions.rst b/docs/tutorial/includes/infinity-fabric-transactions.rst index fd510bd49..b60355bf7 100644 --- a/docs/tutorial/includes/infinity-fabric-transactions.rst +++ b/docs/tutorial/includes/infinity-fabric-transactions.rst @@ -410,7 +410,7 @@ Experiment 5: Coarse-grained, CPU-DRAM reads ---------------------------------------------- In our next fabric experiment, we change our CPU memory allocation to be -:ref:`coarse-grained `. We accomplish this by passing the +`coarse-grained `__. We accomplish this by passing the ``hipHostMalloc`` API the ``hipHostMallocNonCoherent`` flag, to mark the allocation as coarse-grained: diff --git a/docs/tutorial/includes/occupancy-limiters-example.rst b/docs/tutorial/includes/occupancy-limiters-example.rst index bd8129d12..324254533 100644 --- a/docs/tutorial/includes/occupancy-limiters-example.rst +++ b/docs/tutorial/includes/occupancy-limiters-example.rst @@ -303,7 +303,7 @@ SGPR limited ------------ Finally, we modify our kernel once more to make it limited by -:ref:`SGPRs `: +`SGPRs `__: .. code-block:: cpp diff --git a/docs/tutorial/includes/vector-memory-operation-counting.rst b/docs/tutorial/includes/vector-memory-operation-counting.rst index 2797ed8f2..e3dd0deb4 100644 --- a/docs/tutorial/includes/vector-memory-operation-counting.rst +++ b/docs/tutorial/includes/vector-memory-operation-counting.rst @@ -623,7 +623,7 @@ manner. See for further reading on this instruction type. We develop a `simple -kernel `__ +kernel `__ that uses stack memory: .. code-block:: cpp diff --git a/docs/tutorial/profiling-by-example.rst b/docs/tutorial/profiling-by-example.rst index e39239b9d..8a9c85c03 100644 --- a/docs/tutorial/profiling-by-example.rst +++ b/docs/tutorial/profiling-by-example.rst @@ -7,7 +7,7 @@ Profiling by example ******************** The following examples refer to sample :doc:`HIP ` code located in -:fab:`github` :dev-sample:`ROCm/omniperf/blob/amd-mainline/sample <>` and distributed +:fab:`github` :dev-sample:`ROCm/omniperf/blob/dev/sample <>` and distributed as part of Omniperf. .. include:: ./includes/valu-arithmetic-instruction-mix.rst