From 10ba4b76decc038cff554bb030cfeeed27fccb57 Mon Sep 17 00:00:00 2001
From: Young Hui - AMD <145490163+yhuiYH@users.noreply.github.com>
Date: Fri, 31 Jan 2025 21:03:18 -0500
Subject: [PATCH] DOCs: update index and TOC to better organize how-to docs
 (#78)

---
 docs/how-to/configuring-runtime-options.rst | 13 +++++++++
 docs/index.rst                              | 22 ++++++++------
 docs/sphinx/_toc.yml.in                     | 32 ++++++++++++---------
 3 files changed, 44 insertions(+), 23 deletions(-)

diff --git a/docs/how-to/configuring-runtime-options.rst b/docs/how-to/configuring-runtime-options.rst
index 1470e8b10b..9375e15ecc 100644
--- a/docs/how-to/configuring-runtime-options.rst
+++ b/docs/how-to/configuring-runtime-options.rst
@@ -43,6 +43,17 @@ and tweak the default sampling values.
    ROCPROFSYS_SAMPLING_CPUS        = all
    ROCPROFSYS_SAMPLING_GPUS        = $env:HIP_VISIBLE_DEVICES
 
+Use the configuration file
+-----------------------------------
+
+Tell rocprof-systems to use the modified settings by creating the environment variable ``ROCPROFSYS_CONFIG_FILE``
+
+.. code-block:: shell
+
+   export ROCPROFSYS_CONFIG_FILE=~/.rocprof-sys.cfg
+
+See :ref:`creating a configuration file<creating-a-configuration-file>` for more details.
+
 Exploring runtime settings
 -----------------------------------
 
@@ -1191,6 +1202,8 @@ Viewing hardware counters
    | LDSBankConflict:device=0              | The percentage of GPUTime LDS is s... |
    |---------------------------------------|---------------------------------------|
 
+.. _creating-a-configuration-file:
+
 Creating a configuration file
 ========================================
 
diff --git a/docs/index.rst b/docs/index.rst
index c498487be1..bdf9cc1008 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -30,15 +30,19 @@ profiling, how it supports performance analysis, and how to leverage its capabil
 
   .. grid-item-card:: How to
 
-    * :doc:`Configuring and validating the ROCm Systems Profiler environment <./how-to/configuring-validating-environment>`
-    * :doc:`Configuring runtime options <./how-to/configuring-runtime-options>`
-    * :doc:`Sampling the call stack <./how-to/sampling-call-stack>`
-    * :doc:`Instrumenting and rewriting a binary application <./how-to/instrumenting-rewriting-binary-application>`
-    * :doc:`Performing causal profiling <./how-to/performing-causal-profiling>`
-    * :doc:`Understanding the ROCm Systems Profiler output <./how-to/understanding-rocprof-sys-output>`
-    * :doc:`Profiling Python scripts <./how-to/profiling-python-scripts>`
-    * :doc:`Using the ROCm Systems Profiler API <./how-to/using-rocprof-sys-api>`
-    * :doc:`General tips for using ROCm Systems Profiler <./how-to/general-tips-using-rocprof-sys>`
+    * :doc:`Configuring the environment <./how-to/configuring-validating-environment>`
+  
+      * :doc:`Configuring runtime options <./how-to/configuring-runtime-options>`
+ 
+    * :doc:`Profiling <./how-to/general-tips-using-rocprof-sys>`
+    
+      * :doc:`Sampling the call stack <./how-to/sampling-call-stack>`
+      * :doc:`Instrumenting and rewriting a binary application <./how-to/instrumenting-rewriting-binary-application>`
+      * :doc:`Performing causal profiling <./how-to/performing-causal-profiling>`
+      * :doc:`Profiling Python scripts <./how-to/profiling-python-scripts>`
+     
+    * :doc:`Understanding the output <./how-to/understanding-rocprof-sys-output>`
+    * :doc:`Using the ROCm Systems Profiler API <./how-to/using-rocprof-sys-api>`    
 
   .. grid-item-card:: Conceptual
 
diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in
index e6fb884da4..57fbf67997 100644
--- a/docs/sphinx/_toc.yml.in
+++ b/docs/sphinx/_toc.yml.in
@@ -18,23 +18,27 @@ subtrees:
   - caption: How to
     entries:
     - file: how-to/configuring-validating-environment.rst
-      title: Configuring and validating the environment
-    - file: how-to/configuring-runtime-options.rst
-      title: Configuring runtime options
-    - file: how-to/sampling-call-stack.rst
-      title: Sampling the call stack
-    - file: how-to/instrumenting-rewriting-binary-application.rst
-      title: Instrumenting and rewriting a binary application
-    - file: how-to/performing-causal-profiling.rst
-      title: Performing causal profiling
+      title: Configuring the environment
+      subtrees:
+      - entries:
+        - file: how-to/configuring-runtime-options.rst
+          title: Configuring runtime options
+    - file: how-to/general-tips-using-rocprof-sys.rst
+      title: Profiling
+      subtrees:
+      - entries:
+        - file: how-to/sampling-call-stack.rst
+          title: Sampling the call stack
+        - file: how-to/instrumenting-rewriting-binary-application.rst
+          title: Instrumenting and rewriting a binary application
+        - file: how-to/performing-causal-profiling.rst
+          title: Performing causal profiling
+        - file: how-to/profiling-python-scripts.rst
+          title: Profiling Python scripts
     - file: how-to/understanding-rocprof-sys-output.rst
-      title: Understanding the ROCm Systems Profiler output
-    - file: how-to/profiling-python-scripts.rst
-      title: Profiling Python scripts
+      title: Understanding the output
     - file: how-to/using-rocprof-sys-api.rst
       title: Using the ROCm Systems Profiler API
-    - file: how-to/general-tips-using-rocprof-sys.rst
-      title: General tips for using ROCm Systems Profiler
 
   - caption: Conceptual
     entries: