docs: Fix docutils warnings

docs/conceptual/rocprof-sys-feature-set.rst

@@ -2,9 +2,9 @@
    :description: ROCm Systems Profiler feature set documentation and reference
    :keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, profiler, feature set, use cases, tracking, visualization, tool, Instinct, accelerator, AMD
 
-***************************************
-The ROCm Systems Profiler feature set and use cases
-***************************************
+********************************************
+ROCm Systems Profiler features and use cases
+********************************************
 
 `ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ is designed to be highly extensible.
 Internally, it leverages the `Timemory performance analysis toolkit <https://github.com/ROCm/timemory>`_
@@ -129,4 +129,4 @@ broad picture.
 In terms of CPU analysis, ROCm Systems Profiler does not target any specific vendor.
 It works just as well on AMD and non-AMD CPUs.
 With regard to the GPU, ROCm Systems Profiler is currently restricted to HIP and HSA APIs
-and kernels running on AMD GPUs.
+and kernels running on AMD GPUs.

docs/how-to/configuring-runtime-options.rst

@@ -173,7 +173,7 @@ PAPI components from different namespaces:
    about the PAPI library used by ROCm Systems Profiler
    (because ROCm Systems Profiler statically links to ``libpapi``). However, all of these tools are
    installed with the prefix ``rocprof-sys-`` with
-   underscores replaced with hypens, for example ``papi_avail`` becomes ``rocprof-sys-papi-avail``.
+   underscores replaced with hyphens, for example ``papi_avail`` becomes ``rocprof-sys-papi-avail``.
 
 ROCPROFSYS_ROCM_EVENTS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/how-to/general-tips-using-rocprof-sys.rst

@@ -2,9 +2,9 @@
    :description: ROCm Systems Profiler general tips and usage documentation and reference
    :keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, tips, how to, profiler, tracking, visualization, tool, Instinct, accelerator, AMD
 
-**********************************
+********************************************
 General tips for using ROCm Systems Profiler
-**********************************
+********************************************
 
 Follow these general guidelines when using ROCm Systems Profiler. For an explanation of the terms used in this topic, see
 the :doc:`ROCm Systems Profiler glossary <../reference/rocprof-sys-glossary>`.

docs/how-to/performing-causal-profiling.rst

@@ -97,32 +97,32 @@ This can happen in three different ways:
 Key concepts
 -----------------------------------
 
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
-| Concept          | Setting                             | Options                          | Description                                |
-+==================+=====================================+==================================+============================================+
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
+| Concept          | Setting                              | Options                          | Description                                |
++==================+======================================+==================================+============================================+
 | Backend          | ``ROCPROFSYS_CAUSAL_BACKEND``        | ``perf``, ``timer``              | Backend for recording samples required     |
-|                  |                                     |                                  | to calculate the virtual speed-up          |
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
+|                  |                                      |                                  | to calculate the virtual speed-up          |
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
 | Mode             | ``ROCPROFSYS_CAUSAL_MODE``           | ``function``, ``line``           | Select an entire function or individual    |
-|                  |                                     |                                  | line of code for causal experiments        |
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
+|                  |                                      |                                  | line of code for causal experiments        |
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
 | End-to-end       | ``ROCPROFSYS_CAUSAL_END_TO_END``     | Boolean                          | Perform a single experiment during the     |
-|                  |                                     |                                  | entire run (does not require               |
-|                  |                                     |                                  | progress points)                           |
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
+|                  |                                      |                                  | entire run (does not require               |
+|                  |                                      |                                  | progress points)                           |
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
 | Fixed speed-up   | ``ROCPROFSYS_CAUSAL_FIXED_SPEEDUP``  | one or more values from [0, 100] | Virtual speed-up or pool of virtual        |
-|                  |                                     |                                  | speed-ups to randomly select               |
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
+|                  |                                      |                                  | speed-ups to randomly select               |
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
 | Binary scope     | ``ROCPROFSYS_CAUSAL_BINARY_SCOPE``   | regular expression(s)            | Dynamic binaries containing code for       |
-|                  |                                     |                                  | experiments                                |
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
+|                  |                                      |                                  | experiments                                |
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
 | Source scope     | ``ROCPROFSYS_CAUSAL_SOURCE_SCOPE``   | regular expression(s)            | ``<file>`` and/or ``<file>:<line>``        |
-|                  |                                     |                                  | containing code to include in experiments  |
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
+|                  |                                      |                                  | containing code to include in experiments  |
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
 | Function scope   | ``ROCPROFSYS_CAUSAL_FUNCTION_SCOPE`` | regular expression(s)            | Restricts experiments to matching          |
-|                  |                                     |                                  | functions (function mode) or lines of      |
-|                  |                                     |                                  | code within matching functions (line mode) |
-+------------------+-------------------------------------+----------------------------------+--------------------------------------------+
+|                  |                                      |                                  | functions (function mode) or lines of      |
+|                  |                                      |                                  | code within matching functions (line mode) |
++------------------+--------------------------------------+----------------------------------+--------------------------------------------+
 
 .. note::
 

docs/how-to/profiling-python-scripts.rst

@@ -28,7 +28,7 @@ be the same size.
    ``OS`` is the operating system, and ``ABI`` is the application binary interface,
    for example, ``libpyrocprofsys.cpython-38-x86_64-linux-gnu.so``.
 
-Getting Started
+Getting started
 ========================================
 
 The ROCm Systems Profiler Python package is installed in ``lib/pythonX.Y/site-packages/rocprofsys``.
@@ -44,7 +44,7 @@ Both the ``share/rocprofiler-systems/setup-env.sh`` script and the module file i
 environment variable.
 
 Running ROCm Systems Profiler on a Python script
-========================================
+================================================
 
 ROCm Systems Profiler provides an ``rocprof-sys-python`` helper bash script which
 ensures ``PYTHONPATH`` is properly set and the correct Python interpreter is used.
@@ -200,7 +200,7 @@ And then run using the command ``rocprof-sys-python -b -- ./example.py``, ROCm S
    |-----------------------------------------------------------|
 
 ROCm Systems Profiler Python source instrumentation
-========================================
+===================================================
 
 Starting with the unmodified ``example.py`` script above, import the ``rocprofsys`` module:
 
@@ -268,7 +268,7 @@ original ``rocprofsys-python ./example.py`` results:
    numerous functions called when more complex modules are imported, such as ``import numpy``.
 
 ROCm Systems Profiler Python source instrumentation configuration
--------------------------------------------------------------
+-----------------------------------------------------------------
 
 Within the Python source code, the profiler can be configured by directly
 modifying the ``rocprof-sys.profiler.config`` data fields.

docs/how-to/sampling-call-stack.rst

@@ -343,7 +343,7 @@ An rocprof-sys-sample example
 Here is the full output from the previous
 ``rocprof-sys-sample -PTDH -E all -o rocprof-sys-output %tag% -- ./parallel-overhead-locks 30 4 100`` command:
 
-.. code-block:: shell
+.. code-block:: shell-session
 
    $ rocprof-sys-sample -PTDH -E all -o rocprof-sys-output %tag% -c -- ./parallel-overhead-locks 30 4 100
 
@@ -403,3 +403,4 @@ Here is the full output from the previous
    [rocprof-sys][1785877][metadata]> Outputting 'rocprof-sys-output/2024-07-15_16.21/parallel-overhead-locksmetadata-1785877.json' and 'rocprof-sys-output/2024-07-15_16.21/parallel-overhead-locksfunctions-1785877.json'
    [rocprof-sys][1785877][0][rocprofsys_finalize] Finalized: 0.054582 sec wall_clock,    0.000 MB peak_rss,   -1.798 MB page_rss, 0.040000 sec cpu_clock,   73.3 % cpu_util
    [989.312]       perfetto.cc:60128 Tracing session 1 ended, total sessions:0
+

docs/how-to/understanding-rocprof-sys-output.rst

@@ -238,7 +238,7 @@ Metadata JSON Sample
    }
 
 Configuring the ROCm Systems Profiler output
-========================================
+============================================
 
 ROCm Systems Profiler includes a core set of options for controlling the format
 and contents of the output files. For additional information, see the guide on

docs/how-to/using-rocprof-sys-api.rst

@@ -10,7 +10,7 @@ The following example shows how a program can use the ROCm Systems Profiler API
 for run-time analysis.
 
 ROCm Systems Profiler user API example program
-========================================
+==============================================
 
 You can use the ROCm Systems Profiler API to define custom regions to profile and trace.
 The following C++ program demonstrates this technique by calling several functions from the
@@ -157,7 +157,7 @@ ROCm Systems Profiler API, such as ``rocprofsys_user_push_region`` and
    }
 
 Linking the ROCm Systems Profiler libraries to another program
-=======================================================
+==============================================================
 
 To link the ``rocprofiler-systems-user-library`` to another program,
 use the following CMake and ``g++`` directives.
@@ -186,7 +186,7 @@ Output from the API example program
 
 First, instrument and run the program.
 
-.. code-block:: shell
+.. code-block:: shell-session
 
    $ rocprof-sys-instrument -l --min-instructions=8 -E custom_push_region -o -- ./user-api
    ...

docs/index.rst

@@ -2,17 +2,17 @@
    :description: ROCm Systems Profiler documentation and reference
    :keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD
 
-***********************
+***********************************
 ROCm Systems Profiler documentation
-***********************
+***********************************
 
-ROCm Systems Profiler, formerly known as "Omnitrace", is designed for the high-level profiling and comprehensive tracing
+ROCm Systems Profiler is designed for the high-level profiling and comprehensive tracing
 of applications running on the CPU or the CPU and GPU. It supports dynamic binary
 instrumentation, call-stack sampling, and various other features for determining
 which function and line number are currently executing. To learn more, see :doc:`what-is-rocprof-sys`
 
-The code is open and hosted at `<https://github.com/ROCm/rocprofiler-systems>`_.
-
+ROCm Systems Profiler is open source and hosted at `<https://github.com/ROCm/rocprofiler-systems>`__.
+It is the successor to `<https://github.com/ROCm/omnitrace>`__.
 
 .. grid:: 2
   :gutter: 3
@@ -22,17 +22,12 @@ The code is open and hosted at `<https://github.com/ROCm/rocprofiler-systems>`_.
     * :doc:`Quick start <./install/quick-start>`
     * :doc:`ROCm Systems Profiler installation <./install/install>`
 
-
-The documentation is structured as follows:
+Use the following topics to learn more about the advantages of ROCm Systems Profiler in application
+profiling, how it supports performance analysis, and how to leverage its capabilities in practice:
 
 .. grid:: 2
   :gutter: 3
 
-  .. grid-item-card:: Tutorials
-
-    * `GitHub examples <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/examples>`_
-    * :doc:`Video tutorials <./tutorials/video-tutorials>`
-
   .. grid-item-card:: How to
 
     * :doc:`Configuring and validating the ROCm Systems Profiler environment <./how-to/configuring-validating-environment>`
@@ -48,19 +43,24 @@ The documentation is structured as follows:
   .. grid-item-card:: Conceptual
 
     * :doc:`Data collection modes <./conceptual/data-collection-modes>`
-    * :doc:`The ROCm Systems Profiler feature set <./conceptual/rocprof-sys-feature-set>`
+    * :doc:`Features and use cases <./conceptual/rocprof-sys-feature-set>`
 
   .. grid-item-card:: Reference
 
     * :doc:`Development guide <./reference/development-guide>`
-    * :doc:`ROCm Systems Profiler glossary <./reference/rocprof-sys-glossary>`
+    * :doc:`Glossary <./reference/rocprof-sys-glossary>`
     * :doc:`API library <./doxygen/html/files>`
     * :doc:`Class member functions <./doxygen/html/functions>`
     * :doc:`Globals <./doxygen/html/globals>`
     * :doc:`Classes, structures, and interfaces <./doxygen/html/annotated>`
 
+  .. grid-item-card:: Tutorials
+
+    * `GitHub examples <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/examples>`_
+    * :doc:`Video tutorials <./tutorials/video-tutorials>`
+
 To contribute to the documentation, refer to
 `Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
 
 You can find licensing information on the
-`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.
+`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.

docs/license.rst

@@ -0,0 +1,8 @@
+.. meta::
+   :description: ROCm Systems Profiler license
+
+*******
+License
+*******
+
+.. include:: ../LICENSE