Additional edits based on the external review

ROCm · Jul 18, 2024 · 9b01d64 · 9b01d64
1 parent c084348
commit 9b01d64
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 15 deletions.
diff --git a/docs/how-to/profiling-python-scripts.rst b/docs/how-to/profiling-python-scripts.rst
@@ -54,13 +54,17 @@ This means the following commands are effectively equivalent:
 
    omnitrace-python --help
 
+and
+
+.. code-block:: shell
+
    export PYTHONPATH=/opt/omnitrace/lib/python3.8/site-packages:${PYTHONPATH}
    python3.8 -m omnitrace --help
 
 .. note::
 
    ``omnitrace-python`` and ``python -m omnitrace`` use the same command-line syntax 
-   as the ``omnitrace`` executable (``omnitrace-python <OMNITRACE_ARGS> -- <SCRIPT> <SCRIPT_ARGS>``) 
+   as the other ``omnitrace`` executables (``omnitrace-python <OMNITRACE_ARGS> -- <SCRIPT> <SCRIPT_ARGS>``) 
    and has similar options.
 
 Command line options
@@ -109,10 +113,10 @@ Use ``omnitrace-python --help`` to view the available options:
 Selective instrumentation
 -----------------------------------
 
-Similar to the ``omnitrace`` executable, command-line options exist for restricting, 
+Similar to the ``omnitrace-instrument`` executable, command-line options exist for restricting, 
 including, and excluding certain functions and modules, for example, ``--function-exclude "^__init__$"``.
-Alternatively, adding the ``@profile`` decorator to the primary function of interest 
-in combination with the ``-b`` / ``--builtin`` option will narrow the scope of the
+Alternatively, add the ``@profile`` decorator to the primary function of interest 
+in your program and use the ``-b`` / ``--builtin`` command-line option to narrow the scope of the
 instrumentation to this function and its children.
 
 Consider the following Python code (``example.py``):

diff --git a/docs/how-to/understanding-omnitrace-output.rst b/docs/how-to/understanding-omnitrace-output.rst
@@ -240,7 +240,7 @@ Metadata JSON Sample
 Configuring the Omnitrace output
 ========================================
 
-Omnitrace includes a core set of settings for controlling the format 
+Omnitrace includes a core set of options for controlling the format 
 and contents of the output files. For additional information, see the guide on
 :doc:`configuring runtime options <./configuring-runtime-options>`.
 
@@ -249,7 +249,7 @@ Core configuration settings
 
 .. csv-table:: 
    :header: "Setting", "Value", "Description"
-   :widths: 30, 20, 100
+   :widths: 30, 30, 100
 
    "``OMNITRACE_OUTPUT_PATH``", "Any valid path", "Path to folder where output files should be placed"
    "``OMNITRACE_OUTPUT_PREFIX``", "String", "Useful for multiple runs with different arguments. See the next section on output prefix keys."
@@ -349,9 +349,10 @@ Use ``omnitrace-avail --components --filename`` to view the base filename for ea
    | sampling_wall_clock             |     true      | sampling_wall_clock    |
    |---------------------------------|---------------|------------------------|
 
-With the settings ``OMNITRACE_COLLAPSE_THREADS=ON`` and ``OMNITRACE_COLLAPSE_PROCESSES=ON``, which is only valid 
-with full MPI support, the Timemory output
-combines the per-thread and/or per-rank data, which have identical call stacks.
+The ``OMNITRACE_COLLAPSE_THREADS`` and ``OMNITRACE_COLLAPSE_PROCESSES`` settings are 
+only valid when full `MPI support is enabled <../install/install.html#mpi-support-within-omnitrace>`_. 
+When they are set, Timemory combines the per-thread and per-rank data (respectively) of 
+identical call stacks.
 
 The ``OMNITRACE_FLAT_PROFILE`` setting removes all call stack hierarchy. 
 Using ``OMNITRACE_FLAT_PROFILE=ON`` in combination
@@ -360,7 +361,7 @@ min/max measurements regardless of the calling context.
 The ``OMNITRACE_TIMELINE_PROFILE`` setting (with ``OMNITRACE_FLAT_PROFILE=OFF``) effectively 
 generates similar data to that found
 in Perfetto. Enabling timeline and flat profiling effectively generates 
-similar data to ``strace``. However, while Timemory in general
+similar data to ``strace``. However, while Timemory generally
 requires significantly less memory than Perfetto, this is not the case in timeline 
 mode, so use this setting with caution.
 

diff --git a/docs/install/install.rst b/docs/install/install.rst
@@ -271,6 +271,8 @@ in `the Perfetto UI <https://ui.perfetto.dev>`_.
    cmake --build omnitrace-build --target install
    source /opt/omnitrace/share/omnitrace/setup-env.sh
 
+.. _mpi-support-omnitrace:
+
 MPI support within Omnitrace
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/reference/development-guide.rst b/docs/reference/development-guide.rst
@@ -394,12 +394,12 @@ integer indicating how many times to repeat the delay and duration cycle. It is
 possible to perform tasks such as periodically enabling tracing for brief periods
 of time in between long periods without data collection while the application runs. The
 syntax follows the format ``clock_identifier:delay:capture_duration:cycles``, so a value of 
-``10:1:3`` represents the following sequence of operations:
+``10:1:3`` for the last three parameters represents the following sequence of operations:
 
-* 10 seconds where no data is collected, then one second where it is
-* 10 seconds where no data is collected, then one second where it is 
-* 10 seconds where no data is collected, then one second where it is 
-* stop
+* Ten seconds where no data is collected, then one second where it is
+* Ten seconds where no data is collected, then one second where it is 
+* Ten seconds where no data is collected, then one second where it is 
+* Stop
 
 As another example, ``OMNITRACE_TRACE_PERIODS = realtime:10:1:5 process_cputime:10:2:20`` translates
 to this sequence: