Document new ijson.benchmark module

Signed-off-by: Rodrigo Tobar <rtobar@icrar.org>

CHANGELOG.md

@@ -4,6 +4,12 @@
 
 * Removed support for Python 2.7 and 3.4,
   3.5+ is still supported.
+* Distribute the existing `benchmark.py` script
+  as ``ijson.benchmark``.
+  The module is an improved version of the script,
+  supporting #iterations for a given function invocation,
+  multiple input files,
+  and more.
 
 ## [3.2.3]
 

README.rst

@@ -175,6 +175,28 @@ For example::
 Using ``-h/--help`` will show all available options.
 
 
+.. _benchmarking:
+
+Benchmarking
+------------
+
+A command line utility is included with ijson
+to help benchmarking the different methods offered by the package.
+It offers some built-in example inputs
+that try to mimic different scenarios,
+but more importantly it also supports user-provided inputs.
+You can also specify which backends to time,
+number of iterations,
+and more.
+
+The tool is available by running the ``ijson.benchmark`` module.
+For example::
+
+ $> python -m ijson.benchmark my/json/file.json -m items -p values.item
+
+Using ``-h/--help`` will show all available options.
+
+
 ``bytes``/``str`` support
 -------------------------
 
@@ -493,6 +515,10 @@ out of ijson:
   might show better performance.
   See options_ for details.
 
+The benchmarking_ tool should help
+with trying some of these options
+and observing their effect on your input files.
+
 
 .. _faq: