Merge pull request #213 from diydrones/fix_use_of_cmds_clear

Improve docs to reduce issues from #132 mk 2

Author: tcr3dr

docs/examples/flight_replay.rst

@@ -70,6 +70,7 @@ We generate up to 100 waypoints for the vehicle with the following code:
     print "Generating %s waypoints from replay..." % len(messages)
     cmds = v.commands
     cmds.clear()
+    v.flush()
     for i in xrange(0, len(messages)):
         pt = messages[i]
         lat = pt['lat']
@@ -96,5 +97,7 @@ Source code
 
 The full source code at documentation build-time is listed below (`current version on github <https://github.com/diydrones/dronekit-python/blob/master/examples/flight_replay/flight_replay.py>`_):
 
-.. include:: ../../examples/flight_replay/flight_replay.py
-    :literal:
+
+.. literalinclude:: ../../examples/flight_replay/flight_replay.py
+   :language: python
+	

droneapi/lib/__init__.py

@@ -853,6 +853,7 @@ class CommandSequence(object):
 
         cmds = vehicle.commands
         cmds.clear()
+        vehicle.flush()
         lat = -34.364114,
         lon = 149.166022
         altitude = 30.0
@@ -921,6 +922,13 @@ def goto(self, location):
     def clear(self):
         '''
         Clear the command list.
+
+        .. warning::
+
+            Call ``flush()`` immediately after clearing the commands/before adding new commands (see
+            `#132 for more information <https://github.com/diydrones/dronekit-python/issues/132>`_).
+
+        .. todo:: The above note should be removed when https://github.com/diydrones/dronekit-python/issues/132 fixed
         '''
         pass
 

examples/flight_replay/flight_replay.py

@@ -1,12 +1,17 @@
-#
-# This is an example of talking to Droneshare to receive a past flight, and then 'replaying' that flight by sending waypoints
-# to the vehicle that approximates the stored flight log.
-# Usage:
-# * mavproxy.py
-# * module load api
-# * api start flight_replay.py <missionid>
-# (Where mission ID is a numeric mission number from a public droneshare flight)
-#
+"""
+flight_replay.py: 
+
+An example of talking to Droneshare to receive a past flight, and then 'replaying' 
+that flight by sending waypoints to a vehicle.
+
+Start this example as shown below, specifying the 
+missionid (a numeric mission number from a public droneshare flight):
+
+    api start flight_replay.py <missionid>
+
+Full documentation is provided at http://python.dronekit.io/examples/flight_replay.html
+"""
+
 from droneapi.lib import Command
 from pymavlink import mavutil
 import json, urllib, math
@@ -73,6 +78,7 @@ def replay_mission(payload):
     print "Generating %s waypoints from replay..." % len(messages)
     cmds = v.commands
     cmds.clear()
+    v.flush()
     for i in xrange(0, len(messages)):
         pt = messages[i]
         lat = pt['lat']