More comprehensive documentation on scheduler

doc/topics/jobs/schedule.rst

@@ -20,6 +20,123 @@ and could step on each other or otherwise double execute.  The default for
 States are executed on the minion, as all states are. You can pass positional
 arguments and provide a yaml dict of named arguments.
 
+.. code-block:: yaml
+
+    schedule:
+      job1:
+        function: state.sls
+        seconds: 3600
+        args:
+          - httpd
+        kwargs:
+          test: True
+
+This will schedule the command: state.sls httpd test=True every 3600 seconds
+(every hour)
+ 
+.. code-block:: yaml
+
+    schedule:
+      job1:
+        function: state.sls
+        seconds: 3600
+        args:
+          - httpd
+        kwargs:
+          test: True
+        splay: 15
+
+This will schedule the command: state.sls httpd test=True every 3600 seconds
+(every hour) splaying the time between 0 and 15 seconds
+
+.. code-block:: yaml
+
+    schedule:
+      job1:
+        function: state.sls
+        seconds: 3600
+        args:
+          - httpd
+        kwargs:
+          test: True
+        splay:
+          start: 10
+          end: 15
+
+This will schedule the command: state.sls httpd test=True every 3600 seconds
+(every hour) splaying the time between 10 and 15 seconds
+
+.. versionadded:: Helium
+
+Frequency of jobs can also be specified using date strings supported by
+the python dateutil library.
+
+.. code-block:: yaml
+
+    schedule:
+      job1:
+        function: state.sls
+        args:
+          - httpd
+        kwargs:
+          test: True
+        when: 5:00pm
+
+This will schedule the command: state.sls httpd test=True at 5:00pm minion
+localtime.
+
+.. code-block:: yaml
+
+    schedule:
+      job1:
+        function: state.sls
+        args:
+          - httpd
+        kwargs:
+          test: True
+        when:
+            - Monday 5:00pm
+            - Tuesday 3:00pm
+            - Wednesday 5:00pm
+            - Thursday 3:00pm
+            - Friday 5:00pm
+
+This will schedule the command: state.sls httpd test=True at 5pm on Monday, Wednesday
+and Friday, and 3pm on Tuesday and Thursday.
+
+.. code-block:: yaml
+
+    schedule:
+      job1:
+        function: state.sls
+        seconds: 3600
+        args:
+          - httpd
+        kwargs:
+          test: True
+        range:
+            start: 8:00am
+            end: 5:00pm
+
+This will schedule the command: state.sls httpd test=True every 3600 seconds
+(every hour) between the hours of 8am and 5pm.  The range parameter must be a
+dictionary with the date strings using the dateutil format.
+
+.. versionadded:: Helium
+
+The scheduler also supports ensuring that there are no more than N copies of
+a particular routine running.  Use this for jobs that may be long-running
+and could step on each other or pile up in case of infrastructure outage.
+
+The default for maxrunning is 1.
+
+.. code-block:: yaml
+
+    schedule:
+      long_running_job:
+          function: big_file_transfer
+          jid_include: True
+
 States
 ======