update documentation

README.md

@@ -1,6 +1,15 @@
 AMD ROCm Debug Agent Library (ROCdebug-agent)
 =============================================
 
+> [!NOTE]
+> The published documentation is available at
+[ROCR Debug Agent](https://rocm.docs.amd.com/projects/rocr_debug_agent/en/latest/index.html)
+in an organized, easy-to-read format, with search and a table of contents.
+The documentation source files reside in the `rocr_debug_agent/docs` folder of this repository.
+As with all ROCm projects, the documentation is open source.
+For more information on contributing to the documentation, see
+[Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html).
+
 Introduction
 ------------
 

docs/conceptual/user-guide.rst → docs/how-to/user-guide.rst

@@ -1,12 +1,13 @@
 .. meta::
    :description: A library that can be loaded by ROCr to print the AMDGPU wavefront states
-   :keywords: ROCdebug-agent, ROCm, library, tool, rocr, ROCm Debug Agent
+   :keywords: ROCdebug-agent user guide, ROCR Debug Agent user guide, using ROCdebug-agent, using ROCR Debug Agent,
+    ROCdebug-agent user manual, ROCR Debug Agent user manual
 
 .. _user-guide:
 
-===========================
+============================
 ROCR Debug Agent user guide
-===========================
+============================
 
 To display the source text location with the machine code instructions around the wavefront's pc, compile the AMDGPU code objects with ``-ggdb``.  In addition, you can optionally use ``-O0`` to achieve a more intuitive display of the source text location, as higher optimization levels can help to reorder machine code instructions. When ``-ggdb`` is not used, the source line information is unavailable, and only machine code instructions starting at the
 wavefront's pc are printed.

docs/index.rst

@@ -1,24 +1,22 @@
 .. meta::
    :description: A library that can be loaded by ROCr to print the AMDGPU wavefront states
-   :keywords: ROCdebug-agent, ROCm, library, tool, rocr
+   :keywords: ROCdebug-agent documentation, ROCR Debug Agent documentation, rocr, ROCR
 
 .. _index:
 
 ===============================
 ROCR Debug Agent documentation
 ===============================
 
-The ROCR Debug Agent (ROCdebug-agent) is a library that can be loaded by the ROCm software runtime `(ROCR) <https://rocm.docs.amd.com/projects/ROCR-Runtime/en/latest/>`_ to provide the following functionalities:
+The ROCR Debug Agent (ROCdebug-agent) is a library that can be loaded by the ROCm software runtime :doc:`(ROCR) <rocr-runtime:index>` to provide the following functionalities:
 
 - Print the state of all AMDGPU wavefronts that cause a queue error (such as, a memory violation, executing a ``s_trap 2``, or executing an illegal instruction).
 
 - Print the state of all AMDGPU wavefronts by sending a SIGQUIT signal to the process using ``kill -s SIGQUIT <pid>`` command or by pressing ``Ctrl-\``, while the program is executing.
 
-This functionality is provided for all AMDGPUs supported by the ROCm Debugger API Library `(ROCdbgapi) <https://rocm.docs.amd.com/projects/ROCdbgapi/en/latest/>`_.
+This functionality is provided for all AMDGPUs supported by the ROCm Debugger API Library :doc:`(ROCdbgapi) <rocdbgapi:index>`.
 
-You can access ROCdebug-agent code on our `GitHub repository <https://github.com/ROCm/rocr_debug_agent>`_.
-
-The documentation is structured as follows:
+The code is open source and hosted at https://github.com/ROCm/rocr_debug_agent
 
 .. grid:: 2
   :gutter: 3
@@ -27,7 +25,7 @@ The documentation is structured as follows:
 
     * :ref:`installation`
 
-  .. grid-item-card:: Conceptual
+  .. grid-item-card:: How to
 
     * :ref:`user-guide`
 

docs/install/installation.rst

@@ -1,47 +1,54 @@
 .. meta::
    :description: A library that can be loaded by ROCr to print the AMDGPU wavefront states
-   :keywords: ROCdebug-agent, ROCm, library, tool, rocr
+   :keywords: ROCdebug-agent installation, ROCR Debug Agent installation, install ROCdebug-agent, install ROCR Debug Agent,
+    build ROCdebug-agent, build ROCR Debug Agent
+
 
 .. _installation:
 
-==================================
-Installation
-==================================
+==============================
+ROCR debug agent installation
+==============================
 
 This document provides information required to build and install ROCR Debug Agent (ROCdebug-agent) library.
 
 Prerequisites
-------------------
+--------------
 
 - A system supporting ROCm. See the `supported operating systems <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-operating-systems>`_.
 
 - A C++ 17 compiler such as GCC 7 or Clang 5.
 
-- The AMD ROCm software stack. See the `ROCm installation instructions <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/index.html>`_.
+- The AMD ROCm software stack. See the :doc:`ROCm installation instructions <rocm-install-on-linux:index>`.
+
+- Install the required packages according to the OS:
 
-- Packages as per the OS.
+.. tab-set::
 
-  - For Ubuntu 18.04 and Ubuntu 20.04:
+  .. tab-item:: Ubuntu 22.04 and Ubuntu 24.04
+    :sync: ubuntu
 
-  .. code:: shell
+    .. code-block:: shell
 
-    apt install gcc g++ make cmake libelf-dev libdw-dev
+      apt install gcc g++ make cmake libelf-dev libdw-dev
 
-  - For CentOS 8.1 and RHEL 8.1:
+  .. tab-item:: CentOS 8 and RHEL 8/9
+    :sync: rhel
 
-  .. code:: shell
+    .. code-block:: shell
 
-    yum install gcc gcc-c++ make cmake elfutils-libelf-devel elfutils-devel
+      yum install gcc gcc-c++ make cmake elfutils-libelf-devel elfutils-devel
 
-  - For SLES 15 Service Pack 1:
+  .. tab-item:: SLES 15
+    :sync: sles
 
-  .. code:: shell
+    .. code-block:: shell
 
-    zypper install gcc gcc-c++ make cmake libelf-devel libdw-devel
+      zypper install gcc gcc-c++ make cmake libelf-devel libdw-devel
 
 - Python 3.6 or later to run the tests.
 
-- ROCdbgapi library. This can be installed using the ROCdbgapi package as part of the ROCm release. See the instructions to install `ROCdbgapi library <https://rocm.docs.amd.com/projects/ROCdbgapi/en/latest/>`_.
+- :doc:`ROCdbgapi library <rocdbgapi:index>`. This can be installed using the ROCdbgapi package as part of the ROCm release. See the instructions to install :doc:`ROCdbgapi library <rocdbgapi:install/build>`.
 
 Build and install
 -------------------
@@ -75,7 +82,7 @@ The installed ROCdebug-agent library and tests are placed in:
 - <install-prefix>/src/rocm-debug-agent-test/*
 
 Test
--------------
+-----
 
 To test the ROCdebug-agent library, use:
 
@@ -95,7 +102,7 @@ Output:
     100% tests passed, 0 tests failed out of 1
     Total Test time (real) =   1.59 sec
 
-You can run the tests individually outside of the ``CTest`` harness as shown below:
+You can run the tests individually outside of the ``CTest`` harness as shown:
 
 .. code-block:: shell
 

docs/sphinx/_toc.yml.in

@@ -5,9 +5,11 @@ subtrees:
   - caption: Install
     entries:
     - file: install/installation
-  - caption: Conceptual
+      title: Installation
+  - caption: How to
     entries:
-    - file: conceptual/user-guide
+    - file: how-to/user-guide
+      title: User guide
   - caption: About
     entries:
     - file: license