Improve the documentation for automagic.

volatility/framework/automagic/__init__.py

@@ -17,13 +17,17 @@ from volatility.framework.configuration import requirements
 vollog = logging.getLogger(__name__)
 
 
-def available(context, config_path = 'automagic'):
+def available(context):
     """Returns an ordered list of all subclasses of :class:`~volatility.framework.interfaces.automagic.AutomagicInterface`.
 
     The order is based on the priority attributes of the subclasses, in order to ensure the automagics are listed in
     an appropriate order.
+
+    :param context: The context that will contain any automagic configuration values.
+    :type context: volatility.framework.interfaces.context.ContextInterface
     """
     import_files(sys.modules[__name__])
+    config_path = 'automagic'
     return sorted([clazz(context, interfaces.configuration.path_join(config_path, clazz.__name__)) for clazz in
                    class_subclasses(interfaces.automagic.AutomagicInterface)],
                   key = lambda x: x.priority)

volatility/framework/automagic/construct_layers.py

@@ -14,7 +14,7 @@ class ConstructionMagic(interfaces.automagic.AutomagicInterface):
     and from the bottom of the tree upwards, attempt to construct all
     :class:`~volatility.framework.interfaces.configuration.ConstructableRequirementInterface` based classes.
 
-    :warning: This `automagic` should run first to prevent existing configurations getting re-configured.
+    :warning: This `automagic` should run first to allow existing configurations to have been constructed for use by later automagic
     """
     priority = 0
 

volatility/framework/interfaces/automagic.py

@@ -1,4 +1,7 @@
-"""Defines the automagic interfaces for populating the context before a plugin runs"""
+"""Defines the automagic interfaces for populating the context before a plugin runs
+
+Automagic objects attempt to automatically fill configuration values that a user has not filled.
+"""
 
 from abc import ABCMeta, abstractmethod
 
@@ -8,9 +11,28 @@ from volatility.framework.interfaces import configuration as interfaces_configur
 
 
 class AutomagicInterface(interfaces_configuration.ConfigurableInterface, metaclass = ABCMeta):
-    """Class that defines an automagic component that can help fulfill a Requirement"""
+    """Class that defines an automagic component that can help fulfill a Requirement
+
+    These classes are callable with the following parameters:
+
+    :param context: The context in which to store configuration data that the automagic might populate
+    :type context: ~volatility.framework.interfaces.context.ContextInterface
+    :param config_path: Configuration path where the configurable's data under the context's config lives
+    :type config_path: str
+    :param configurable: The top level configurable whose requirements may need statisfying
+    :type configurable: ~volatility.framework.interfaces.configuration.ConfigurableInterface
+    :param progress_callback: An optional function accepting a percentage and optional description to indicate
+        progress during long calculations
+
+    .. note::
+
+        The `context` provided here may be different to that provided during initialization.  The `context` provided at
+        initialization should be used for local configuration of the automagic itself, the `context` provided during
+        the call is to be populated by the automagic.
+    """
 
     priority = 10
+    """An ordering to indicate how soon this automagic should be run"""
 
     def __init__(self, context, config_path, *args, **kwargs):
         super().__init__(context, config_path)