DOCs: update index and TOC to better organize how-to docs (#78)

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
 ========================================
 

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 the 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:`Configuring runtime options <./how-to/configuring-runtime-options>`
-    * :doc:`Instrumenting and rewriting a binary application <./how-to/instrumenting-rewriting-binary-application>`
+ 
-    * :doc:`Performing causal profiling <./how-to/performing-causal-profiling>`
+    * :doc:`Profiling <./how-to/general-tips-using-rocprof-sys>`
-    * :doc:`Understanding the ROCm Systems Profiler output <./how-to/understanding-rocprof-sys-output>`
+    
-    * :doc:`Profiling Python scripts <./how-to/profiling-python-scripts>`
+      * :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>`    
-    * :doc:`General tips for using ROCm Systems Profiler <./how-to/general-tips-using-rocprof-sys>`
 
   .. grid-item-card:: Conceptual
 

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
+      title: Configuring the environment
-    - file: how-to/configuring-runtime-options.rst
+      subtrees:
-      title: Configuring runtime options
+      - entries:
-    - file: how-to/sampling-call-stack.rst
+        - file: how-to/configuring-runtime-options.rst
-      title: Sampling the call stack
+          title: Configuring runtime options
-    - file: how-to/instrumenting-rewriting-binary-application.rst
+    - file: how-to/general-tips-using-rocprof-sys.rst
-      title: Instrumenting and rewriting a binary application
+      title: Profiling
-    - file: how-to/performing-causal-profiling.rst
+      subtrees:
-      title: Performing causal profiling
+      - 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
+      title: Understanding the output
-    - file: how-to/profiling-python-scripts.rst
-      title: Profiling Python scripts
     - 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: