API modifications to fix missing/confusing reference

[hamishwillee]

The current API Reference is built from droneapi.lib module by Sphinx, which pulls it from comments in /droneapi/module/api.py and droneapi/lib/init.py. I've done a bit of a comparison of what is in the files and what is documented and have some suggestions:

DONE

1. Documentation in init refers to objects as "base class" and has comments like "implemented in subclass". This is useful for a developer, but confusing for a user. If the base class is an interface, then it should just say what the interface does.

   HW I have updated these cases in the source so they are marked as "Internal notes"

2. Attributes of Vehicle are documented in a table in the interface class. It would be better if these were part of the public "imported" API.

   HW I have updated these cases in the source using py:attribute markup. However it would be better if these were "properly" in the public API.

Split out

1. CommandSequence.takeoff is missing in public API/documentation - created separate defect Add CommandSequence.takeoff to the public API #70
2. CommandSequence.next setter is not appearing in public API - DOCs: Some setters are not being pulled into the public API #83 83
3. Order source by preferred order of display to improve readability Reorder __init__.py layout to improve API reference documentation #84

[hamishwillee]

FYI, just separated out the discussion related to showing partially implemented APIs to #65

[hamishwillee]

This is the comparison review (full)

Comparison review

Comparison of documented API with the .py definitions to verify documentation is complete
https://github.com/diydrones/dronekit-python/blob/master/droneapi/module/api.py
https://github.com/diydrones/dronekit-python/blob/master/droneapi/lib/__init__.py
http://python.dronekit.io/automodule.html

• Things present in files but not documented

@next.setter - def next(self, value): Present in api/init, only documented in init. Not in output
CommandSequence.takeoff - present in api but not init.

class droneapi.lib.Vehicle

• The docs contain table of information for the properties included from the header. These are defined in MPVehicle(Vehicle) but not imported. It would be better to import them IMO rather than have them in a table, if only to ensure that it is obvious what is changed when we change the API
  That said, what appears to be missing from the docs is
• "mount_status" - in MPVehicle but not documented elsewhere
• def wait_init(self): in MPVehicle
• The documentation mentions user and ap_ - board-specific parameters. However it is not clear where these are defined? Certainly they appear nowhere in the API.
• Things that include spurious information
  notify_observers, get_vehicles, next (and setter) - all talk about implementation of subclass
  APIConnection, Authinfo refer to themselves as "Base class for ..." If this documentation is for end users rather than developers, that is not a useful description.
• Things in one file but not others:

api.py: class MPParameters(Parameters): def wait_valid(self): - this method not documented in the output or the init.py file.

Api.py

This is what is in https://github.com/diydrones/dronekit-python/blob/master/droneapi/module/api.py

class MPParameters(Parameters):
    def wait_valid(self):

class MPCommandSequence(CommandSequence):
    def download(self): # BIG FIXME - wait for full wpt download before allowing any of the accessors to work
    def wait_valid(self):
    def takeoff(self, alt=None):
    def goto(self, l):
    def clear(self):
    def add(self, cmd):
    def count(self):
    def next(self):
    def next(self, index): Next Setter

class MPVehicle(Vehicle):
    def flush(self):
    def mode(self):
    def mode(self, v): @mode.setter
    def location(self):
    def velocity(self):
    def attitude(self):
    def gps_0(self):
    def armed(self):
    def armed(self, value): @armed.setter
    def groundspeed(self):
    def airspeed(self):
    def mount_status(self):
    def channel_override(self):
    def channel_override(self, newch): @channel_override.setter
    def channel_readback(self):
    def commands(self):
    def send_mavlink(self, message):
    def message_factory(self):
    def wait_init(self):

class MPAPIConnection(APIConnection):
    def get_vehicles(self, query=None):


class APIThread(threading.Thread):
    def kill(self):
    def run(self):


class APIModule(mp_module.MPModule):
 All internal 

init.py

This is what is in https://github.com/diydrones/dronekit-python/blob/master/droneapi/lib/__init__.py

def web_connect(authinfo):
def local_connect():

class APIException(Exception):
class AuthInfo(object):
class ConnectionInfo(object):
class Attitude(object):
class Location(object):
class GPSInfo(object):
class VehicleMode(object):
class APIConnection(object):
    def get_vehicles(self, query=None):
    def exit(self):


class HasObservers(object):
    def add_attribute_observer(self, attr_name, observer):
    def remove_attribute_observer(self, attr_name, observer):
    def notify_observers(self, attr_name):


class Vehicle(HasObservers):
    def commands(self):
    def parameters(self):
    def delete(self):
    def get_mission(self, query_params):
    def message_factory(self):
    def send_mavlink(self, message):
    def set_mavlink_callback(self, callback):
    def flush(self):

class Mission(object):
class Parameters(HasObservers):
class Command(mavutil.mavlink.MAVLink_mission_item_message):
class CommandSequence(object):
    def download(self):
    def wait_valid(self):
    def goto(self, location):
    def clear(self):
    def add(self, cmd):
    def count(self):
    def next(self):
    def next(self, value):     @next.setter

Documentation set on python.dronekit.io

This is what is documented.

class droneapi.lib.APIConnection
  exit
  get_vehicles(query=None)
exception droneapi.lib.APIException(msg)
class droneapi.lib.Attitude(pitch, yaw, roll)
class droneapi.lib.AuthInfo(username, password)
class droneapi.lib.Command(target_system, target_component, seq, frame, command, current, autocontinue, param1, param2, param3, param4, x, y, z)
class droneapi.lib.CommandSequence
  add(cmd)
  clear()
  count
  download()
  goto(location)
  next
  wait_valid()
class droneapi.lib.ConnectionInfo(mavproxy_options)
class droneapi.lib.GPSInfo(eph, epv, fix_type, satellites_visible)
class droneapi.lib.Location(lat, lon, alt=None, is_relative=True)
class droneapi.lib.Mission
class droneapi.lib.Parameters
  add_attribute_observer(attr_name, observer)
  remove_attribute_observer(attr_name, observer)

class droneapi.lib.Vehicle
  - Attributes are document separately - would be good if they were documented /exposed by the API.
  add_attribute_observer(attr_name, observer)
  commands
  delete()
  flush()
  get_mission(query_params)
  message_factory
  notify_observers(attr_name)
  remove_attribute_observer(attr_name, observer)
  send_mavlink(message)
  set_mavlink_callback(callback)


class droneapi.lib.VehicleMode(name)
droneapi.lib.local_connect()
droneapi.lib.web_connect(authinfo)

[hamishwillee]

Closing this issue as all parts have either been dealt with, or pushed out into other issues.