docstring cleanup

doc/index.rst

@@ -1,4 +1,5 @@
 .. Mycroft documentation master file
+
 Mycroft-core technical documentation
 ====================================
 

doc/source/mycroft.audio.rst

@@ -1,6 +1,8 @@
-mycroft.audio package
+mycroft.audio
 ====================
 
-wait_while_speaking
--------------------
-.. autofunction:: mycroft.audio.wait_while_speaking
+.. automodule:: mycroft.audio
+  :members:
+    is_speaking,
+    stop_speaking,
+    wait_while_speaking

doc/source/mycroft.rst

@@ -5,25 +5,25 @@ mycroft.skills
 ==============
 
 MycroftSkill class - Base class for all Mycroft skills
-------------------
+------------------------------------------------------
 
 .. autoclass:: mycroft.MycroftSkill
     :members:
 
 CommonIoTSkill class
--------------------
+--------------------
 .. autoclass:: mycroft.skills.common_iot_skill.CommonIoTSkill
     :show-inheritance:
     :members:
 
 CommonPlaySkill class
--------------------
+---------------------
 .. autoclass:: mycroft.skills.common_play_skill.CommonPlaySkill
     :show-inheritance:
     :members:
 
 CommonQuerySkill class
--------------------
+----------------------
 .. autoclass:: mycroft.skills.common_query_skill.CommonQuerySkill
     :show-inheritance:
     :members:
@@ -56,6 +56,12 @@ removes_context decorator
 -------------------------
 .. autofunction:: mycroft.removes_context
 
+mycroft.audio
+==================
+
+.. toctree::
+    mycroft.audio
+
 mycroft.filesystem
 ==================
 
@@ -73,16 +79,15 @@ mycroft.util
 
 .. toctree::
     mycroft.util.parse
+
 Parsing functions for extracting data from natural speech.
 
 .. toctree::
     mycroft.util.format
+
 Formatting functions for producing natural speech from common datatypes such as numbers, dates and times.
 
 .. toctree::
     mycroft.util.time
-A collection of functions for handling local, system and global times.
 
------------------
-.. automodule::
-    mycroft.util.time
+A collection of functions for handling local, system and global times.

doc/source/mycroft.util.format.rst

@@ -1,5 +1,5 @@
 mycroft.util.format
-==================
+===================
 
 .. automodule:: mycroft.util.format
   :members:

doc/source/mycroft.util.rst

@@ -25,22 +25,6 @@ play_ogg
 ---------
 .. autofunction:: mycroft.util.play_ogg
 
-extract_datetime
-----------------
-.. autofunction:: mycroft.util.extract_datetime
-
-extract_number
--------------
-.. autofunction:: mycroft.util.extract_number
-
-normalize
----------
-.. autofunction:: mycroft.util.normalize
-
-nice_number
------------
-.. autofunction:: mycroft.util.nice_number
-
 resolve_resource_file
 ---------------------
 .. autofunction:: mycroft.util.resolve_resource_file

mycroft/api/__init__.py

@@ -113,7 +113,7 @@ def send(self, params, no_refresh=False):
         The method handles Etags and will return a cached response value
         if nothing has changed on the remote.
 
-        Arguments:
+        Args:
             params (dict): request parameters
             no_refresh (bool): optional parameter to disable refreshs of token
 
@@ -156,9 +156,10 @@ def get_response(self, response, no_refresh=False):
 
         Will try to refresh the access token if it's expired.
 
-        Arguments:
+        Args:
             response (requests Response object): Response to parse
             no_refresh (bool): Disable refreshing of the token
+
         Returns:
             data fetched from server
         """
@@ -373,7 +374,7 @@ def get_skill_settings(self):
     def upload_skill_metadata(self, settings_meta):
         """Upload skill metadata.
 
-        Arguments:
+        Args:
             settings_meta (dict): skill info and settings in JSON format
         """
         return self.request({
@@ -386,7 +387,7 @@ def upload_skills_data(self, data):
         """ Upload skills.json file. This file contains a manifest of installed
         and failed installations for use with the Marketplace.
 
-        Arguments:
+        Args:
              data: dictionary with skills data from msm
         """
         if not isinstance(data, dict):
@@ -512,7 +513,7 @@ def is_paired(ignore_errors=True):
 def check_remote_pairing(ignore_errors):
     """Check that a basic backend endpoint accepts our pairing.
 
-    Arguments:
+    Args:
         ignore_errors (bool): True if errors should be ignored when
 
     Returns:

mycroft/audio/audioservice.py

@@ -91,10 +91,11 @@ def get_services(services_folder):
 def setup_service(service_module, config, bus):
     """Run the appropriate setup function and return created service objects.
 
-    Arguments:
+    Args:
         service_module: Python module to run
         config (dict): Mycroft configuration dict
         bus (MessageBusClient): Messagebus interface
+
     Returns:
         (list) List of created services.
     """
@@ -116,11 +117,12 @@ def setup_service(service_module, config, bus):
 def load_internal_services(config, bus, path=None):
     """Load audio services included in Mycroft-core.
 
-    Arguments:
+    Args:
         config: configuration dict for the audio backends.
         bus: Mycroft messagebus
         path: (default None) optional path for builtin audio service
               implementations
+
     Returns:
         List of started services
     """
@@ -150,7 +152,7 @@ def load_internal_services(config, bus, path=None):
 def load_plugins(config, bus):
     """Load installed audioservice plugins.
 
-    Arguments:
+    Args:
         config: configuration dict for the audio backends.
         bus: Mycroft messagebus
 
@@ -173,7 +175,7 @@ def load_services(config, bus, path=None):
     parameter) for services and plugins registered with the
     "mycroft.plugin.audioservice" entrypoint group.
 
-    Arguments:
+    Args:
         config: configuration dict for the audio backends.
         bus: Mycroft messagebus
         path: (default None) optional path for builtin audio service
@@ -261,7 +263,7 @@ def load_services(self):
     def wait_for_load(self, timeout=3 * MINUTES):
         """Wait for services to be loaded.
 
-        Arguments:
+        Args:
             timeout (float): Seconds to wait (default 3 minutes)
         Returns:
             (bool) True if loading completed within timeout, else False.

mycroft/audio/services/__init__.py

@@ -23,7 +23,7 @@
 class AudioBackend(metaclass=ABCMeta):
     """Base class for all audio backend implementations.
 
-    Arguments:
+    Args:
         config (dict): configuration dict for the instance
         bus (MessageBusClient): Mycroft messagebus emitter
     """
@@ -50,7 +50,7 @@ def clear_list(self):
     def add_list(self, tracks):
         """Add tracks to backend's playlist.
 
-        Arguments:
+        Args:
             tracks (list): list of tracks.
         """
 
@@ -61,7 +61,7 @@ def play(self, repeat=False):
         Starts playing the first track in the playlist and will contiune
         until all tracks have been played.
 
-        Arguments:
+        Args:
             repeat (bool): Repeat playlist, defaults to False
         """
 
@@ -119,14 +119,14 @@ def restore_volume(self):
     def seek_forward(self, seconds=1):
         """Skip X seconds.
 
-        Arguments:
+        Args:
             seconds (int): number of seconds to seek, if negative rewind
         """
 
     def seek_backward(self, seconds=1):
         """Rewind X seconds.
 
-        Arguments:
+        Args:
             seconds (int): number of seconds to seek, if negative jump forward.
         """
 

mycroft/audio/speech.py

@@ -108,7 +108,7 @@ def handle_speak(event):
 def mute_and_speak(utterance, ident, listen=False):
     """Mute mic and start speaking the utterance using selected tts backend.
 
-    Arguments:
+    Args:
         utterance:  The sentence to be spoken
         ident:      Ident tying the utterance to the source query
     """
@@ -152,7 +152,7 @@ def _get_mimic_fallback():
 def mimic_fallback_tts(utterance, ident, listen):
     """Speak utterance using fallback TTS if connection is lost.
 
-    Arguments:
+    Args:
         utterance (str): sentence to speak
         ident (str): interaction id for metrics
         listen (bool): True if interaction should end with mycroft listening
@@ -177,7 +177,7 @@ def handle_stop(event):
 def init(messagebus):
     """Start speech related handlers.
 
-    Arguments:
+    Args:
         messagebus: Connection to the Mycroft messagebus
     """
 

mycroft/client/enclosure/__main__.py

@@ -37,7 +37,7 @@ def on_error(e='Unknown'):
 def create_enclosure(platform):
     """Create an enclosure based on the provided platform string.
 
-    Arguments:
+    Args:
         platform (str): platform name string
 
     Returns:

mycroft/client/enclosure/mark1/mouth.py

@@ -93,7 +93,7 @@ def text(self, event=None):
     def __display(self, code, clear_previous, x_offset, y_offset):
         """ Write the encoded image to enclosure screen.
 
-        Arguments:
+        Args:
             code (str):           encoded image to display
             clean_previous (str): if "True" will clear the screen before
                                   drawing.
@@ -119,7 +119,7 @@ def __display(self, code, clear_previous, x_offset, y_offset):
 
     def display(self, event=None):
         """ Display a Mark-1 specific code.
-        Arguments:
+        Args:
             event (Message): messagebus message with data to display
         """
         code = ""
@@ -139,7 +139,7 @@ def display_image(self, event=None):
         The method uses PIL to convert the image supplied into a code
         suitable for the Mark-1 display.
 
-        Arguments:
+        Args:
             event (Message): messagebus message with data to display
         """
         if not event:

mycroft/client/speech/data_structures.py

@@ -21,7 +21,7 @@ class RollingMean:
     The optimization is made for cases where value retrieval is made at a
     comparative rate to the sample additions.
 
-    Arguments:
+    Args:
         mean_samples: Number of samples to use for mean value
     """
     def __init__(self, mean_samples):
@@ -66,7 +66,7 @@ class CyclicAudioBuffer:
     TODO: The class is still unoptimized and performance can probably be
     enhanced.
 
-    Arguments:
+    Args:
         size (int): size in bytes
         initial_data (bytes): initial buffer data
     """
@@ -78,7 +78,7 @@ def __init__(self, size, initial_data):
     def append(self, data):
         """Add new data to the buffer, and slide out data if the buffer is full
 
-        Arguments:
+        Args:
             data (bytes): binary data to append to the buffer. If buffer size
                           is exceeded the oldest data will be dropped.
         """