fix text and typo in benchmark_example

Author: tharittk

tutorials/benchmark_example.py

@@ -1,9 +1,18 @@
 r"""
 Benchmark Utility in PyLops-MPI
-=========================
-This tutorial demonstrates how to use the bencmark utility of PyLops-MPI. It contains various
-function calling pattern that may come up during the benchmarking.
+===============================
+This tutorial demonstrates how to use the :py:func:`pylops_mpi.utils.benchmark` and
+:py:func:`pylops_mpi.utils.mark` utility methods in PyLops-MPI. It contains various
+function calling pattern that may come up during the benchmarking of a distributed code.
+
+:py:func:`pylops_mpi.utils.benchmark` is a decorator used to decorate any
+function to measure its execution time from start to finish
+:py:func:`pylops_mpi.utils.mark` is a function used inside the benchmark-decorated
+function to provide fine-grain time measurements.
 """
+
+import sys
+import logging
 import numpy as np
 from mpi4py import MPI
 from pylops_mpi import DistributedArray, Partition
@@ -16,15 +25,9 @@
        'axis': 1}
 
 ###############################################################################
-# Let's start by import the utility
+# Let's start by import the utility and a simple exampple
 from pylops_mpi.utils.benchmark import benchmark, mark
 
-###############################################################################
-# :py:func:`pylops_mpi.utils.benchmark` is a decorator used to decorate any
-# function to measure its execution time from start to finish
-# :py:func:`pylops_mpi.utils.mark` is a function used inside the benchmark-decorated
-# function to provide fine-grain time measurements. Let's start with a simple example
-
 
 @benchmark
 def inner_func(par):
@@ -38,14 +41,15 @@ def inner_func(par):
 ###############################################################################
 # When we call :py:func:`inner_func`, we will see the result
 # of the benchmark print to standard output. If we want to customize the
-# function name in the printout, we can pass the parameter to the :py:func:`benchmark`
+# function name in the printout, we can pass the parameter `description`
+# to the :py:func:`benchmark`
 # i.e., :py:func:`@benchmark(description="printout_name")`
 
 inner_func(par)
 
 ###############################################################################
-# We may want to get the finer time measurement by timing the execution time from arbitary lines
-# of code. :py:func:`pylops_mpi.utils.mark` provides such utitlity
+# We may want to get the fine-grained time measurements by timing the execution
+# time of arbitary lines of code. :py:func:`pylops_mpi.utils.mark` provides such utitlity.
 
 
 @benchmark
@@ -60,14 +64,14 @@ def inner_func_with_mark(par):
 
 
 ###############################################################################
-# Now when we run, we get the detail time measurement. Noted that there is a tag
-# [decorator] to the function name to distinguish between the start-to-end time measuredment of
-# top-level function and those that comes from :py:func:`pylops_mpi.utils.mark`
+# Now when we run, we get the detailed time measurement. Note that there is a tag
+# [decorator] next to the function name to distinguish between the start-to-end time
+# measurement of the top-level function and those that comes from :py:func:`pylops_mpi.utils.mark`
 inner_func_with_mark(par)
 
 ###############################################################################
-# This utility also supports the nested functions. Let's define the outer function
-# that internally calls decorated :py:func:`inner_func_with_mark`
+# This utility benchmarking routines can also be nested. Let's define
+# an outer function that internally calls the decorated :py:func:`inner_func_with_mark`
 
 
 @benchmark
@@ -83,24 +87,20 @@ def outer_func_with_mark(par):
 
 ###############################################################################
 # If we run :py:func:`outer_func_with_mark`, we get the time measurement nicely
-# printout with the nested indentation to specify that nested calls.
+# printed out with the nested indentation to specify that nested calls.
 outer_func_with_mark(par)
 
 
 ###############################################################################
 # In some cases, we may want to write benchmark output to a text file.
 # :py:func:`pylops_mpi.utils.benchmark` also takes the py:class:`logging.Logger`
-# in its argument. Let's first import the logging package and construct our logger
+# in its argument.
+# Here we define a simple :py:func:`make_logger()`. We set the :py:func:`logger.propagate = False`
+# to isolate the logging of our benchmark from that of the rest of the code
 
-import sys
-import logging
 save_file = True
 file_path = "benchmark.log"
 
-###############################################################################
-# Here we define a simple :py:func:`make_logger()`. We set the :py:func:`logger.propagate = False`
-# isolate the logging of our benchmark from that of the rest of the code
-
 
 def make_logger(save_file=False, file_path=''):
     logger = logging.getLogger(__name__)