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]

projects/rocprofiler-compute/docs/install/core-install.rst

@@ -0,0 +1,236 @@
+.. meta::
+   :description: Omniperf installation and deployment
+   :keywords: Omniperf, ROCm, profiler, tool, Instinct, accelerator, AMD,
+              install, deploy, Grafana, client, configuration, modulefiles
+
+*********************************
+Installing and deploying Omniperf
+*********************************
+
+Omniperf consists of two installation components.
+
+* :ref:`Omniperf core installation <core-install>` (client-side)
+
+  * Provides the core application profiling capability.
+  * Allows the collection of performance counters, filtering by hardware
+    block, dispatch, kernel, and more.
+  * Provides a CLI-based analysis mode.
+  * Provides a standalone web interface for importing analysis metrics.
+
+* :doc:`Grafana server for Omniperf <grafana-setup>` (server-side) (*optional*)
+
+  * Hosts the MongoDB backend and Grafana instance.
+  * Is packaged in a Docker container for easy setup.
+
+Determine what you need to install based on how you would like to interact with
+Omniperf. See the following decision tree to help determine what installation is
+right for you.
+
+.. image:: ../data/install/install-decision-tree.png
+   :align: center
+   :alt: Decision tree for installing and deploying Omniperf
+   :width: 800
+
+.. _core-install:
+ 
+Core installation
+=================
+
+The core Omniperf application requires the following basic software
+dependencies. As of ROCm 6.2, the core Omniperf is included with your ROCm
+installation.
+
+* Python ``>= 3.8``
+* CMake ``>= 3.19``
+* ROCm ``>= 5.7.1``
+
+Omniperf depends on a number of Python packages documented in the top-level
+``requirements.txt`` file. Install these *before* configuring Omniperf.
+
+.. tip::
+
+   If looking to build Omniperf as a developer, consider these additional
+   requirements.
+
+   .. list-table::
+
+       * - ``docs/sphinx/requirements.txt``
+         - Python packages required to build this documentation from source.
+
+       * - ``requirements-test.txt``
+         - Python packages required to run Omniperf's CI suite using PyTest.
+
+The recommended procedure for Omniperf usage is to install into a shared file
+system so that multiple users can access the final installation. The
+following steps illustrate how to install the necessary Python dependencies
+using `pip <https://packaging.python.org/en/latest/>`_ and Omniperf into a
+shared location controlled by the ``INSTALL_DIR`` environment variable.
+
+.. _core-install-cmake-vars:
+
+Configuration variables
+-----------------------
+The following installation example leverages several
+`CMake <https://cmake.org/cmake/help/latest>`_ project variables defined as
+follows.
+
+.. list-table::
+    :header-rows: 1
+
+    * - CMake variable
+      - Description
+
+    * - ``CMAKE_INSTALL_PREFIX``
+      - Controls the install path for Omniperf files.
+
+    * - ``PYTHON_DEPS``
+      - Specifies an optional path to resolve Python package dependencies.
+
+    * - ``MOD_INSTALL_PATH``
+      - Specifies an optional path for separate Omniperf modulefile installation.
+
+.. _core-install-steps:
+
+Install from source
+-------------------
+
+#. A typical install begins by downloading the latest release tarball available
+   from `<https://github.com/ROCm/omniperf/releases>`__. From there, untar and
+   navigate into the top-level directory.
+
+   ..
+      {{ config.version }} substitutes the Omniperf version in ../conf.py
+
+   .. datatemplate:nodata::
+
+      .. code-block:: shell
+
+         tar xfz omniperf-v{{ config.version }}.tar.gz
+         cd omniperf-v{{ config.version }}
+
+#. Next, install Python dependencies and complete the Omniperf configuration and
+   install process.
+
+   .. datatemplate:nodata::
+
+      .. code-block:: shell
+
+         # define top-level install path
+         export INSTALL_DIR=<your-top-level-desired-install-path>
+
+         # install python deps
+         python3 -m pip install -t ${INSTALL_DIR}/python-libs -r requirements.txt
+
+         # configure Omniperf for shared install
+         mkdir build
+         cd build
+         cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{{ config.version }} \
+                 -DPYTHON_DEPS=${INSTALL_DIR}/python-libs \
+                 -DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles ..
+
+         # install
+         make install
+
+   .. tip::
+
+      You might need to ``sudo`` the final installation step if you don't have
+      write access for the chosen installation path.
+
+#. Upon successful installation, your top-level installation directory should
+   look like this.
+
+   .. datatemplate:nodata::
+
+      .. code-block:: shell
+
+         $ ls $INSTALL_DIR
+         modulefiles  {{ config.version }}  python-libs
+
+.. _core-install-modulefiles:
+
+Execution using modulefiles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The installation process includes the creation of an environment modulefile for
+use with `Lmod <https://lmod.readthedocs.io>`_. On systems that support Lmod,
+you can register the Omniperf modulefile directory and setup your environment
+for execution of Omniperf as follows.
+
+.. datatemplate:nodata::
+
+   .. code-block:: shell
+
+      $ module use $INSTALL_DIR/modulefiles
+      $ module load omniperf
+      $ which omniperf
+      /opt/apps/omniperf/{{ config.version }}/bin/omniperf
+
+      $ omniperf --version
+      ROC Profiler:   /opt/rocm-5.1.0/bin/rocprof
+
+      omniperf (v{{ config.version }})
+
+.. tip::
+
+   If you're relying on an Lmod Python module locally, you may wish to customize
+   the resulting Omniperf modulefile post-installation to include extra
+   module dependencies.
+
+Execution without modulefiles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use Omniperf without the companion modulefile, update your ``PATH``
+settings to enable access to the command line binary. If you installed Python
+dependencies in a shared location, also update your ``PYTHONPATH``
+configuration.
+
+.. datatemplate:nodata::
+
+   .. code-block:: shell
+
+      export PATH=$INSTALL_DIR/{{ config.version }}/bin:$PATH
+      export PYTHONPATH=$INSTALL_DIR/python-libs
+
+.. _core-install-package:
+
+Install via package manager
+---------------------------
+
+Once ROCm (minimum version 6.2.0) is installed, you can install Omniperf using
+your operating system's native package manager using the following commands.
+See :doc:`rocm-install-on-linux:index` for guidance on installing the ROCm
+software stack.
+
+.. tab-set::
+
+   .. tab-item:: Ubuntu
+
+      .. code-block:: shell
+
+         $ sudo apt install omniperf
+         $ pip install -r /opt/rocm/libexec/omniperf/requirements.txt
+
+   .. tab-item:: Red Hat Enterprise Linux
+
+      .. code-block:: shell
+
+         $ sudo dnf install omniperf
+         $ pip install -r /opt/rocm/libexec/omniperf/requirements.txt
+
+   .. tab-item:: SUSE Linux Enterprise Server
+
+      .. code-block:: shell
+
+         $ sudo zypper install omniperf
+         $ pip install -r /opt/rocm/libexec/omniperf/requirements.txt
+
+.. _core-install-rocprof-var:
+
+ROCProfiler
+-----------
+
+Omniperf relies on :doc:`ROCProfiler <rocprofiler:index>`'s ``rocprof`` binary
+during the profiling process. Normally, the path to this binary is detected
+automatically, but you can override the path by the setting the optional
+``ROCPROF`` environment variable.
+

projects/rocprofiler-compute/docs/install/grafana-setup.rst

@@ -0,0 +1,209 @@
+.. meta::
+   :description: Omniperf Grafana server installation and deployment
+   :keywords: Omniperf, ROCm, profiler, tool, Instinct, accelerator, AMD,
+              install, deploy, Grafana, server, configuration, GUI
+
+****************************************
+Setting up a Grafana server for Omniperf
+****************************************
+
+A Grafana server is *not required* to profile or analyze performance data
+from the CLI. It's a supplementary mechanism to help you import performance
+data and examine it in a detailed
+`Grafana <https://github.com/grafana/grafana>`_ dashboard GUI.
+
+Learn about installing and configuring the main Omniperf tool in
+:ref:`core-install`.
+
+Setting up a Grafana instance for Omniperf requires the following basic software
+dependencies.
+
+* `Docker Engine <https://docs.docker.com/engine/install/>`_
+
+The recommended process for enabling the server-side of Omniperf is to use the
+provided ``Dockerfile`` to build the Grafana and MongoDB instance.
+
+.. _grafana-mongodb-setup:
+
+Set up Grafana and MongoDB
+==========================
+
+Once you've decided where to host the Grafana and MongoDB instance, complete the
+the following setup instructions.
+
+Install MongoDB utilities
+-------------------------
+
+Omniperf uses the
+`mongoimport <https://www.mongodb.com/docs/database-tools/mongoimport/>`_
+utility to upload data to your Grafana instance's backend database.
+
+Use the following commands to install MongoDB utilities for Ubuntu 20.04.
+
+.. code-block:: bash
+
+   $ wget https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2004-x86_64-100.6.1.deb
+   $ sudo apt install ./mongodb-database-tools-ubuntu2004-x86_64-100.6.1.deb
+
+.. note::
+
+   Find installation instructions for other distributions in
+   `MongoDB Database Tools Downloads <https://www.mongodb.com/download-center/database-tools/releases/archive>`_.
+
+.. _grafana-persistent-storage-setup:
+
+Set up persistent storage
+-------------------------
+
+Bind MongoDB to a directory on the host OS to create a local backup in case of a
+crash or reset. This is called *creating a persistent volume*.
+
+.. code-block:: bash
+
+   $ sudo mkdir -p /usr/local/persist && cd /usr/local/persist/
+   $ sudo mkdir -p grafana-storage mongodb
+   $ sudo docker volume create --driver local --opt type=none --opt device=/usr/local/persist/grafana-storage --opt o=bind grafana-storage
+   $ sudo docker volume create --driver local --opt type=none --opt device=/usr/local/persist/mongodb --opt o=bind grafana-mongo-db
+
+.. _grafana-docker-container:
+
+Build and launch the Docker container
+-------------------------------------
+
+You're now ready to build your ``Dockerfile``. Navigate to your Omniperf install
+directory to begin.
+
+.. code-block:: bash
+
+   $ cd grafana
+   $ sudo docker-compose build
+   $ sudo docker-compose up -d
+
+The TCP ports for Grafana (``4000``) and MongoDB (``27017``) in the Docker
+container are mapped to ``14000`` and ``27018``, respectively, on the host side.
+
+.. tip::
+
+   In the event that either your Grafana or MongoDB instance crashes fatally,
+   just restart the server. Navigate to your install directory and run:
+
+   .. code-block::
+
+      $ sudo docker-compose down
+      $ sudo docker-compose up -d
+
+.. _grafana-dashboard-setup:
+
+Set up the Grafana dashboard
+----------------------------
+
+Once you've launched your Docker container you should be able to reach Grafana
+at ``http://<host-ip>:14000``. The default login credentials for your first-time
+Grafana setup are:
+
+* **Username**: ``admin``
+* **Password**: ``admin``
+
+.. figure:: ../data/install/grafana_welcome.png
+   :align: center
+   :alt: Grafana dashboard welcome screen
+   :width: 800
+
+   Grafana's welcome screen.
+
+.. _grafana-datasource-setup:
+
+Configure the MongoDB data source
+---------------------------------
+
+You must configure your MongoDB data source in Grafana before first-time use.
+Navigate to Grafana's **Configuration** page to add the "Omniperf Data"
+connection.
+
+.. figure:: ../data/install/datasource_config.jpg
+   :align: center
+   :alt: Grafana data source configuration
+   :width: 800
+
+   Grafana's Configuration page.
+
+Configure the following fields in the data source settings.
+
+.. list-table::
+   :stub-columns: 1
+
+   * - HTTP URL
+     - ``http://localhost:3333``
+
+   * - MongoDB URL
+     - ``mongodb://temp:temp123@\<host-ip>:27018/admin?authSource=admin``
+
+   * - Database Name
+     - ``admin``
+
+After configuring these fields, click **Save & test** to make sure your
+connection is successful.
+
+.. figure:: ../data/install/datasource_settings.jpg
+   :align: center
+   :alt: Grafana data source settings
+   :width: 800
+
+   Grafana data source settings.
+
+.. note::
+
+   To avoid potential DNS issues, you might need to use the actual IP address
+   for the host node in the MongoDB URL.
+
+.. _grafana-import-dashboard-file:
+
+Import the Omniperf dashboard file
+----------------------------------
+
+From the **Create** → **Import** page, upload the dashboard file,
+``/dashboards/Omniperf_v{__VERSION__}_pub.json`` from the
+:doc:`Omniperf tarball <core-install>`.
+
+Edit both the dashboard **Name** and the **Unique identifier (UID)** fields to
+uniquely identify the dashboard. Click **Import** to complete the process.
+
+.. figure:: ../data/install/import_dashboard.png
+   :align: center
+   :alt: Grafana's import dashboard
+   :width: 800
+
+   Grafana's Import dashboard.
+
+.. _grafana-select-workload:
+
+Select and load the Omniperf workload
+-------------------------------------
+
+Once you have imported a dashboard you're ready to begin. Start by browsing
+available dashboards and selecting the dashboard you have just imported.
+
+.. figure:: ../data/install/opening_dashboard.png
+   :align: center
+   :alt: Opening your Omniperf dashboard in Grafana
+   :width: 800
+
+   Opening your Omniperf profiling dashboard in Grafana.
+
+Remember that you need to upload workload data to the MongoDB backend before
+analyzing in your Grafana interface. See a detailed example of this in 
+:ref:`grafana-gui-import`.
+
+After a workload has been successfully uploaded, you should be able to select it
+from the workload dropdown located at the top of your Grafana dashboard.
+
+.. figure:: ../data/install/grafana_workload_selection.png
+   :align: center
+   :alt: Omniperf workload selection in Grafana
+   :width: 800
+
+   Selecting your Omniperf workload in Grafana.
+
+For more information on how to use the Grafana interface for analysis see
+:doc:`/how-to/analyze/grafana-gui`.
+