doc: work on usage commands

bh107 · May 24, 2017 · 02f69a4 · 02f69a4
1 parent ea0433a
commit 02f69a4
Show file tree

Hide file tree

Showing 6 changed files with 47 additions and 11 deletions.
diff --git a/benchpress/__init__.py b/benchpress/__init__.py
@@ -33,12 +33,8 @@
 def _suite_schema():
     from os.path import join, realpath, dirname
     import json
-    import sys
-    print >> sys.stderr, join(dirname(realpath(__file__)), "suite_schema.json")
-    print >> sys.stderr, os.getcwd()
-    print >> sys.stderr, os.listdir(join(dirname(realpath(__file__))))
     try:
         return json.load(open(join(dirname(realpath(__file__)), "suite_schema.json"), "r"))
-    except IOError:
+    except IOError:  # readthedocs cannot find "suite_schema.json"
         return None
 suite_schema = _suite_schema()
diff --git a/benchpress/suites/numpy_example.py b/benchpress/suites/numpy_example.py
@@ -13,6 +13,7 @@
         bash_cmd = "python {root}/benchmarks/{script}/python_numpy/{script}.py --size={size}" \
             .format(root=BP_ROOT, script=name, size=size)
         cmd_list.append(bp.command(bash_cmd, full_label))
+        print bp.command(bash_cmd, full_label)
 
 # Finally, we build the Benchpress suite, which is written to `--output`
 bp.create_suite(cmd_list)
diff --git a/benchpress/visualizer/util.py b/benchpress/visualizer/util.py
@@ -189,15 +189,15 @@ def default_argparse(description, multiple_result_files=False):
     if multiple_result_files:
         parser.add_argument(
             "results",
-            metavar="FILE",
+            metavar="FILE_LIST",
             type=argparse.FileType('r'),
             nargs='+',
             help="JSON file containing results (accept multiple files)"
         )
     else:
         parser.add_argument(
             "results",
-            metavar="FILE_LIST",
+            metavar="FILE",
             type=argparse.FileType('r'),
             help="JSON file containing results"
         )
@@ -210,9 +210,10 @@ def default_argparse(description, multiple_result_files=False):
     )
     parser.add_argument(
         "--parse-regex",
+        metavar="RegEx",
         type=str,
         default='elapsed-time: ([\d.]+)',
-        help="How to parse the result of each run. The RegEX should contain exactly one group."
+        help="How to parse the result of each run. For each RegEx match, group one is recorded as a result."
     )
     parser.add_argument(
         "--py-type",

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -14,7 +14,7 @@ Contents:
 |                              |                              |
 |    quickstart                |                              |
 |    install                   |    suites                    |
-|    usage_commands            |    benchmarks                |
-|    suite_file                |                              |
+|    suite_file                |    benchmarks                |
+|    usage_commands            |                              |
 |    reference/index           |                              |
 +------------------------------+------------------------------+
diff --git a/doc/source/suite_file.rst b/doc/source/suite_file.rst
@@ -1,8 +1,29 @@
+.. _SuiteFile:
+
 ==============
 The Suite File
 ==============
 
-The suite file specifies the set of commands to execute and the results of said executions. The suite format is defined in `json-schema <http://json-schema.org>`_:
+The suite file contains the set of commands to execute and the results of said executions.
+In Python, it is easy to create a suite file. You start by creating a list of :py:class:`dict` where each :py:class:`dict` specify a command to execute such as::
+
+    [{
+      'label': 'X-ray/10*10*1', # The label of the command
+      'cmd': 'python xraysim.py --size=10*10*1',  # The command to execute
+      'env': {}  # The environment variables that will be defined before execution
+    }, {
+      'label': 'X-ray/20*10*1',
+      'cmd': 'python xraysim.py --size=20*10*1',
+      'env': {}
+    }]
+
+And then you call :py:func:`benchpress.benchpress.create_suite`, which writes the suite file at the location specified with the command line argument ``--output``.
+
+
+JSON schema
+-----------
+
+The suite format is defined in `json-schema <http://json-schema.org>`_:
 
 .. raw:: html
 

diff --git a/doc/source/usage_commands.rst b/doc/source/usage_commands.rst
@@ -6,17 +6,34 @@ Benchpress provides a set of binaries for running and visualize the suite file :
 
 bp-run
 ------
+After you have created a benchmark suite file (see. :ref:`SuiteFile`), you can then use ``bp-run`` to *execute* the suite:
 
 .. literalinclude:: autodoc_usage_commands/bp-run.txt
 
 bp-cli
 ------
+At any point, you can read the result of the finished executions within a benchmark suite file.
+``bp-cli`` prints the benchmark results to the terminal:
 
 .. literalinclude:: autodoc_usage_commands/bp-cli.txt
 
+bp-cli-series
+-------------
+
+.. literalinclude:: autodoc_usage_commands/bp-cli-series.txt
+
 bp-chart
 --------
 
 .. literalinclude:: autodoc_usage_commands/bp-chart.txt
 
 
+bp-chart-series
+---------------
+
+.. literalinclude:: autodoc_usage_commands/bp-chart-series.txt
+
+bp-raw
+------
+
+.. literalinclude:: autodoc_usage_commands/bp-raw.txt