Initial commit of open source Workload Automation.

doc/source/conventions.rst

@@ -0,0 +1,74 @@
+===========
+Conventions
+===========
+
+Interface Definitions
+=====================
+
+Throughout this documentation a number of stubbed-out class definitions will be
+presented showing an interface defined by a base class that needs to be
+implemented by the deriving classes. The following conventions will be used when
+presenting such an interface:
+
+   - Methods shown raising :class:`NotImplementedError` are abstract and *must*
+     be overridden by subclasses.
+   - Methods with ``pass`` in their body *may* be (but do not need to be)  overridden 
+     by subclasses. If not overridden, these methods will default to the base
+     class implementation, which may or may not be a no-op (the ``pass`` in the
+     interface specification does not necessarily mean that the method does not have an 
+     actual implementation in the base class).
+
+     .. note:: If you *do* override these methods you must remember to call the
+               base class' version inside your implementation as well.
+
+   - Attributes who's value is shown as ``None`` *must* be redefined by the
+     subclasses with an appropriate value.
+   - Attributes who's value is shown as something other than ``None`` (including
+     empty strings/lists/dicts) *may* be (but do not need to be) overridden by 
+     subclasses. If not overridden, they will default to the value shown.
+
+Keep in mind that the above convention applies only when showing interface
+definitions and may not apply elsewhere in the documentation. Also, in the
+interest of clarity, only the relevant parts of the base class definitions will
+be shown some members (such as internal methods) may be omitted.
+
+
+Code Snippets
+=============
+
+Code snippets provided are intended to be valid Python code, and to be complete.
+However, for the sake of clarity, in some cases only the relevant parts will be
+shown with some details omitted (details that may necessary to validity of the code 
+but not to understanding of the concept being illustrated). In such cases, a
+commented ellipsis will be used to indicate that parts of the code have been
+dropped. E.g.  ::
+
+        # ...
+
+        def update_result(self, context):
+           # ...
+           context.result.add_metric('energy', 23.6, 'Joules', lower_is_better=True)
+
+        # ...
+
+
+Core Class Names
+================
+
+When core classes are referenced throughout the documentation, usually their
+fully-qualified names are given e.g. :class:`wlauto.core.workload.Workload`.
+This is done so that Sphinx_ can resolve them and provide a link. While
+implementing extensions, however, you should *not* be importing anything
+directly form under :mod:`wlauto.core`. Instead, classes you are meant to
+instantiate or subclass have been aliased in the root :mod:`wlauto` package,
+and should be imported from there, e.g. ::
+
+        from wlauto import Workload
+
+All examples given in the documentation follow this convention. Please note that
+this only applies to the :mod:`wlauto.core` subpackage; all other classes
+should be imported for their corresponding subpackages.
+
+.. _Sphinx: http://sphinx-doc.org/
+
+