Merge pull request #40 from hpc/scheduler-plugin-doc

Scheduler plugin documentation

docs/plugins/result_parsers.md

@@ -13,7 +13,7 @@ the [yapsy-plugin](basics.md#plugin_nameyapsy-plugin).
 
 #### Writing the Source
 
-You begin writing the source with the command class definition.
+You begin writing the source with the result parser class definition.
 Don't forget to include the result_parsers module. We have been 
 using the CamelCase naming convention to 
 keep everything the same. It is simply:
@@ -23,12 +23,12 @@ from pavilion import result_parsers
 class ResultParserName(result_parsers.ResultParser):
 ```
 
-At the minimum each command will require four methods: 
+At the minimum each result parser class will require four methods: 
 `__init__`, `get_config_items`, `_check_args`, and `__call__`. 
 
 ##### Writing `__init__()`:
 The `__init__` method should only take one argument, that one argument being 
-`self`, as this will be used to initialize the new command. 
+`self`, as this will be used to initialize the new result parser. 
 
 In this method, you will call `super().__init__()` and
 pass the following arguments: 

docs/plugins/schedulers.md

@@ -0,0 +1,62 @@
+# Scheduler Plugins
+
+This page is an overview of scheduler plugins and how to write them.
+
+Scheduler plugins take care of the scheduling part of testing. For this
+documentation, we will use the `raw` scheduler plugin for examples. 
+
+## Writing Scheduler Plugins
+
+Scheduler plugins require the [source code](#writing-the-source) and the
+[yapsy-plugin](basics.md#plugin_nameyapsy-plugin).
+
+### Writing the Source
+At the very least, each scheduler plugin will have a 
+[variable class](#the-variables-class) and the actual 
+[scheduler class](#the-scheduler-class)
+
+#### The Variables Class
+Every scheduler plugin module has to have a variables class that is a child of 
+the `SchedulerVariables` class found in `schedulers.py`. 
+
+```python
+class RawVars(SchedulerVariables):
+```
+
+To add a variable, add a method with the same name as the variable
+and decorate it with either `@sched_var` or `dfr_sched_var` (for deferred
+variables). 
+
+For example, the `raw` scheduler has a variable called `cpus`. The 
+method for this variable is as follows:
+
+```python
+@var_method
+def cpus(self):
+	"""Total CPUs (includes hyperthreading cpus)."""
+	return self.sched_data['cpus']
+```
+
+#### The Scheduler Class
+
+Each scheduler plugin also requires a class that inherits from `SchedulerPlugin`
+in `schedulers.py`. This class will need to have a member variable called 
+`VAR_CLASS` that has the value of the [variable class](#the-variables-class)
+
+```python
+class Raw(SchedulerPlugin):
+	VAR_CLASS = RawVars
+```
+
+This class will have to implement at least the following methods:
+* `__init__` - Initializes scheduler plugin. This method will need to call 
+`SchedulerPlugin.__init__` with at least the parameters `self`, `name`, and
+`description`
+* `_filter_nodes` - This method should check the system and make sure that there
+are appropriate nodes available.
+* `_in_alloc` - This method determines whether we're on a scheduled node.
+* `get_conf` - This method needs to return the necessary configuration items.
+* `_get_data` - This method gets data relevant to the scheduler. 
+* `job_status` - This method gets the job status from the scheduler.
+* `_schedule` - This method runs the kickoff script generated by Pavilion.
+* `_cancel_job` - This method tells Pavilion how to cancel a test via scheduler.