doc: add building of instrument method map

doc/Makefile

@@ -51,7 +51,7 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf source/api/*
 	rm -rf source/plugins/*
-	rm -rf source/instrumentation_method_map.rst
+	rm -rf source/developer_reference/instrument_method_map.rst
 
 coverage:
 	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage

doc/build_instrument_method_map.py

@@ -18,14 +18,14 @@ import sys
 import string
 from copy import copy
 
-from wa.framework.instrumentation import SIGNAL_MAP, Priority
+from wa.framework.instrument import SIGNAL_MAP, Priority
 from wa.utils.doc import format_simple_table
 
 
 CONVINIENCE_ALIASES = ['initialize', 'setup', 'start', 'stop', 'process_workload_result',
                        'update_result', 'teardown', 'finalize']
 
-OUTPUT_TEMPLATE_FILE =  os.path.join(os.path.dirname(__file__), 'source', 'instrumentation_method_map.template')
+OUTPUT_TEMPLATE_FILE =  os.path.join(os.path.dirname(__file__), 'source', 'instrument_method_map.template')
 
 
 def escape_trailing_underscore(value):
@@ -33,7 +33,7 @@ def escape_trailing_underscore(value):
         return value[:-1] + '\_'
 
 
-def generate_instrumentation_method_map(outfile):
+def generate_instrument_method_map(outfile):
     signal_table = format_simple_table([(k, v) for k, v in SIGNAL_MAP.iteritems()],
                                        headers=['method name', 'signal'], align='<<')
     priority_table = format_simple_table(zip(Priority.names, Priority.values),

doc/source/conf.py

@@ -33,6 +33,7 @@ from build_plugin_docs import (generate_plugin_documentation,
                                generate_run_config_documentation,
                                generate_meta_config_documentation,
                                generate_target_documentation)
+from build_instrument_method_map import generate_instrument_method_map
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -322,6 +323,7 @@ def setup(app):
     generate_target_documentation('plugins')
     generate_run_config_documentation('run_config')
     generate_meta_config_documentation('run_config')
+    generate_instrument_method_map(os.path.join('developer_reference', 'instrument_method_map.rst'))
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')

doc/source/developer_reference/writing_extensions.rst

@@ -714,10 +714,11 @@ hooked up to the supported signals. Once a signal is broadcasted, the
 corresponding registered method is invoked.
 
 Each method in Instrument must take two arguments, which are self and context.
-Supported signals can be found in the :ref:`Signals Documentation
+Supported method and their corresponding signals can be found in the
-<instruments_method_map>` To make implementations easier and common, the basic
+:ref:`Signals Documentation <instruments_method_map>` To make implementations
-steps to add new instrument is similar to the steps to add new workload and an
+easier and common, the basic steps to add new instrument is similar to the steps
-example can be found :ref:`here <adding-an-instrument-example>`.
+to add new workload and an example can be found
+:ref:`here <adding-an-instrument-example>`.
 
 .. _instrument-api:
 
@@ -871,6 +872,9 @@ Below is a simple instrument that measures the execution time of a workload::
             execution_time = self.end_time - self.start_time
             context.add_metric('execution_time', execution_time, 'seconds')
 
+
+.. include:: developer_reference/instrument_method_map.rst
+
 .. _adding-an-output-processor:
 
 Adding an Output processor

doc/source/instrument_method_map.template

@@ -0,0 +1,17 @@
+.. _instruments_method_map:
+
+Instrumentation Signal-Method Mapping
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Instrument methods get automatically hooked up to signals based on their names. Mostly, the method
+name correponds to the name of the signal, however there are a few convienience aliases defined
+(listed first) to make  easier to relate instrumenation code to the workload execution model.
+
+$signal_names
+
+The methods above may be decorated with on the listed decorators to  set the priority of the
+Instrument method realive to other callbacks registered for the signal (within the same priority
+level, callbacks are invoked in the order they were registered). The table below shows the mapping
+of the decorator to the corresponding priority:
+
+$priority_prefixes