Merge pull request #165 from gamingrobot/docstrings-conv

Convert to Google Docstrings

CONTRIBUTING.rst

@@ -52,6 +52,11 @@ Hack away at the code
 
 Have fun!
 
+Docstrings
+~~~~~~~~~~
+
+We use Google Style Python Docstrings, an example can be found `here <https://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html>`__
+
 Test your changes
 ~~~~~~~~~~~~~~~~~
 

spockbot/mcdata/recipes.py

@@ -67,7 +67,8 @@ def total_ingredient_amounts(recipe):
 
 def ingredient_positions(recipe):
     """
-    returns dict{ (item_id, metadata) -> [ (x, y, amount), ... ] }
+    Returns:
+        dict: In the form { (item_id, metadata) -> [ (x, y, amount), ... ] }
     """
     positions = defaultdict(list)
     for y, row in enumerate(recipe.in_shape):

spockbot/mcdata/windows.py

@@ -12,7 +12,9 @@ def make_slot_check(wanted):
     """
     Creates and returns a function that takes a slot and checks
     if it matches the wanted item.
-    :param wanted: function(Slot) or Slot or itemID or (itemID, metadata)
+
+    Args:
+        wanted: function(Slot) or Slot or itemID or (itemID, metadata)
     """
     if isinstance(wanted, types.FunctionType):
         return wanted  # just forward the slot check function
@@ -151,25 +153,31 @@ def get_packet(self, inv_plugin):
         """
         Called by send_click() to prepare the sent packet.
         Abstract method.
-        :param inv_plugin: inventory plugin instance
+
+        Args:
+            inv_plugin (InventoryPlugin): inventory plugin instance
         """
         raise NotImplementedError()
 
     def apply(self, inv_plugin):
         """
         Called by on_success().
         Abstract method.
-        :param inv_plugin: inventory plugin instance
+
+        Args:
+            inv_plugin (InventoryPlugin): inventory plugin instance
         """
         raise NotImplementedError()
 
     def on_success(self, inv_plugin, emit_set_slot):
         """
         Called when the click was successful
         and should be applied to the inventory.
-        :param inv_plugin: inventory plugin instance
-        :param emit_set_slot: function to signal a slot change,
-                              should be InventoryPlugin().emit_set_slot
+
+        Args:
+            inv_plugin (InventoryPlugin): inventory plugin instance
+            emit_set_slot (func): function to signal a slot change,
+                should be InventoryPlugin().emit_set_slot
         """
         self.dirty = set()
         self.apply(inv_plugin)

spockbot/mcp/yggdrasil.py

@@ -32,7 +32,8 @@ def authenticate(self, username=None, password=None, client_token=None):
         Generate an access token using an username and password. Any existing
         client token is invalidated if not provided.
 
-        :rtype: :class:`dict` Response or error dict
+        Returns:
+            dict: Response or error dict
         """
         endpoint = '/authenticate'
         self.username = username or self.username
@@ -59,7 +60,8 @@ def refresh(self, client_token=None, access_token=None):
         Generate an access token with a client/access token pair. Used
         access token is invalidated.
 
-        :rtype: :class:`dict` Response or error dict
+        Returns:
+            dict: Response or error dict
         """
         endpoint = '/refresh'
         self.access_token = access_token or self.access_token
@@ -79,7 +81,8 @@ def signout(self, username=None, password=None):
         """
         Invalidate access tokens with a username and password.
 
-        :rtype: :class:`dict` Empty or error dict
+        Returns:
+            dict: Empty or error dict
         """
         endpoint = '/signout'
         self.username = username or self.username
@@ -95,7 +98,8 @@ def invalidate(self, client_token=None, access_token=None):
         """
         Invalidate access tokens with a client/access token pair
 
-        :rtype: :class:`dict` Empty or error dict
+        Returns:
+            dict: Empty or error dict
         """
         endpoint = '/invalidate'
         self.access_token = access_token or self.access_token
@@ -111,7 +115,8 @@ def validate(self, access_token=None):
         """
         Check if an access token is valid
 
-        :rtype: :class:`dict` Empty or error dict
+        Returns:
+            dict: Empty or error dict
         """
         endpoint = '/validate'
         self.access_token = access_token or self.access_token

spockbot/plugins/helpers/interact.py

@@ -133,8 +133,11 @@ def click_block(self, pos, face=1, cursor_pos=Vector3(8, 8, 8),
         """
         Click on a block.
         Examples: push button, open window, make redstone ore glow
-        :param face: side of the block on which the block is placed on
-        :param cursor_pos: where to click inside the block, each dimension 0-15
+
+        Args:
+            face (int): side of the block on which the block is placed on
+            cursor_pos (Vector3): where to click inside the block,
+                each dimension 0-15
         """
         if look_at_block and self.auto_look:
             # TODO look at cursor_pos

spockbot/plugins/helpers/inventory.py

@@ -24,7 +24,9 @@ def total_stored(self, wanted, slots=None):
         """
         Calculates the total number of items of that type
         in the current window or given slot range.
-        :param wanted: function(Slot) or Slot or itemID or (itemID, metadata)
+
+        Args:
+            wanted: function(Slot) or Slot or itemID or (itemID, metadata)
         """
         if slots is None:
             slots = self.window.slots
@@ -36,7 +38,9 @@ def find_slot(self, wanted, slots=None):
         Returns the first slot containing the item or None if not found.
         Searches the given slots or, if not given,
         active hotbar slot, hotbar, inventory, open window in this order.
-        :param wanted: function(Slot) or Slot or itemID or (itemID, metadata)
+
+        Args:
+            wanted: function(Slot) or Slot or itemID or (itemID, metadata)
         """
         for slot in self.find_slots(wanted, slots):
             return slot
@@ -47,7 +51,9 @@ def find_slots(self, wanted, slots=None):
         Yields all slots containing the item.
         Searches the given slots or, if not given,
         active hotbar slot, hotbar, inventory, open window in this order.
-        :param wanted: function(Slot) or Slot or itemID or (itemID, metadata)
+
+        Args:
+            wanted: function(Slot) or Slot or itemID or (itemID, metadata)
         """
         if slots is None:
             slots = self.inv_slots_preferred + self.window.window_slots