Improve documentation

docs/source/api.rst

@@ -5,12 +5,21 @@ pycozmo package
  :nosignatures:
  :toctree: generated
 
+ pycozmo.audiokinetic.exception
+ pycozmo.audiokinetic.soundbank
+ pycozmo.audiokinetic.soundbanksinfo
+ pycozmo.audiokinetic.wem
+ pycozmo.activity
  pycozmo.anim
+ pycozmo.anim_controller
  pycozmo.anim_encoder
  pycozmo.audio
+ pycozmo.behavior
+ pycozmo.brain
  pycozmo.camera
  pycozmo.client
  pycozmo.conn
+ pycozmo.emotions
  pycozmo.event
  pycozmo.exception
  pycozmo.filter

pycozmo/activity.py

@@ -1,6 +1,6 @@
 """
 
-Activity classes.
+Activity representation and reading.
 
 """
 

pycozmo/anim.py

@@ -1,6 +1,6 @@
 """
 
-Animation clip preprocessing and playback.
+Animation clip representation, reading, and preprocessing.
 
 """
 

pycozmo/anim_controller.py

@@ -1,3 +1,8 @@
+"""
+
+Animation controller for audio, image, and animation playback.
+
+"""
 
 from typing import List, Tuple, Any, Optional, Iterable
 from threading import Thread, Lock
@@ -11,6 +16,7 @@
 
 
 class AnimationQueue:
+ """ Synchronized animation queue class. """
 
  MAXLEN = 4500 # ~2.5 min of frames
 
@@ -66,6 +72,7 @@ def get(self) -> Tuple[bytes, bytes, Tuple[Any]]:
 
 
 class AnimationController:
+ """ Animation controller class. """
 
  def __init__(self, cli):
  self.cli = cli

pycozmo/audio.py

@@ -25,6 +25,7 @@
 
 
 def load_wav(filename: str) -> List[protocol_encoder.OutputAudio]:
+ """ Load a WAVE file into a list of OutputAudio packets. """
  with wave.open(filename, "r") as w:
  sampwidth = w.getsampwidth()
  framerate = w.getframerate()
@@ -47,6 +48,7 @@ def load_wav(filename: str) -> List[protocol_encoder.OutputAudio]:
 
 
 def bytes_to_cozmo(byte_string: bytes, rate_correction: int, channels: int) -> bytearray:
+ """ Convert a 744 sample, 16-bit audio frame into a U-law encoded frame. """
  out = bytearray(744)
  n = channels * rate_correction
  bs = struct.unpack('{}h'.format(int(len(byte_string) / 2)), byte_string)[0::n]

pycozmo/audiokinetic/exception.py

@@ -1,6 +1,6 @@
 """
 
-AudioKinetic WWave exceptions.
+AudioKinetic WWise exceptions.
 
 """
 

pycozmo/audiokinetic/wem.py

@@ -0,0 +1,5 @@
+"""
+
+AudioKinetic WWise WEM file representation and reading.
+
+"""

pycozmo/behavior.py

@@ -1,6 +1,6 @@
 """
 
-Behavior classes.
+Behavior representation and reading.
 
 """
 

pycozmo/brain.py

@@ -1,6 +1,6 @@
 """
 
-Brain class.
+Brain class - high level behavior and emotion engine.
 
 """
 

pycozmo/camera.py

@@ -113,6 +113,7 @@ def minicolor_to_jpeg(minicolor, width, height):
 
 
 def mini_to_jpeg_helper(mini, width, height, header):
+ """ Low-level mini*ToJpeg format to normal JPEG format conversion. """
  buffer_in = mini.tolist()
  curr_len = len(mini)
 

pycozmo/client.py

@@ -1,6 +1,6 @@
 """
 
-Cozmo protocol client.
+Cozmo protocol client and high-level API.
 
 """
 
@@ -39,6 +39,7 @@
 
 
 class Client(event.Dispatcher):
+ """ Cozmo protocol client and high-level API class. """
 
  def __init__(self,
  robot_addr: Optional[Tuple[str, int]] = None,

pycozmo/conn.py

@@ -1,6 +1,6 @@
 """
 
-Cozmo protocol connection.
+Cozmo protocol low-level client and server connection.
 
 """
 
@@ -40,6 +40,7 @@
 
 
 class SendThread(Thread):
+ """ Cozmo protocol connection send thread. """
 
  COLLECT_INTERVAL = 1/30 / 3
  ACK_TIMEOUT = 3 * 1/30
@@ -195,6 +196,7 @@ def reset(self) -> None:
 
 
 class ReceiveThread(Thread):
+ """ Cozmo protocol connection receive thread. """
 
  def __init__(self,
  sock: socket.socket,
@@ -332,6 +334,7 @@ def reset(self):
 
 
 class Connection(Thread, event.Dispatcher):
+ """ Cozmo protocol low-level connection implementing bot client and server sides. """
 
  IDLE = 1
  CONNECTING = 2

pycozmo/emotions.py

@@ -1,6 +1,6 @@
 """
 
-Emotion classes.
+Emotion representation and reading.
 
 """
 

pycozmo/exception.py

@@ -1,6 +1,6 @@
 """
 
-Exceptions declaration.
+Exception declarations.
 
 """
 

pycozmo/filter.py

@@ -1,6 +1,6 @@
 """
 
-ID filtering.
+ID filtering for logging.
 
 """
 

pycozmo/frame.py

@@ -1,6 +1,6 @@
 """
 
-Cozmo protocol frame.
+Cozmo protocol frame representation and encoding and decoding.
 
 """
 

pycozmo/json_loader.py

@@ -13,10 +13,8 @@ def load_json_file(filename: str) -> Dict:
  with open(filename, 'r') as f:
  filtered_json = ''
  for line in f.readlines():
- # ignore urls (don't know what they might be used for)
- if '\"url\":' not in line:
- # get all characters before '//'
- filtered_json += line.split('//')[0]
+ # get all characters before '//'
+ filtered_json += line.split('//')[0]
  return json.loads(filtered_json)