Merge pull request #2178 from forslund/feature/docs-format-parse

Feature/docs format parse

doc/source/mycroft.rst

@@ -1,28 +1,10 @@
 mycroft package
 ===============
 
-.. toctree::
-    mycroft.util
-
-.. toctree::
-    mycroft.util.parse
-
-mycroft.util.time - time handling functions
------------------
-.. automodule::
-    mycroft.util.time
-    :members:
-
-Api class
----------
-.. autoclass:: mycroft.Api
-    :members:
-
-
 mycroft.skills
 ==============
 
-MycroftSkill class - base class for all Mycroft skills
+MycroftSkill class - Base class for all Mycroft skills
 ------------------
 
 .. autoclass:: mycroft.MycroftSkill
@@ -74,3 +56,25 @@ removes_context decorator
 -------------------------
 .. autofunction:: mycroft.removes_context
 
+
+mycroft.util
+===============
+
+.. toctree::
+    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

doc/source/mycroft.util.format.rst

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

doc/source/mycroft.util.parse.rst

@@ -1,18 +1,5 @@
 mycroft.util.parse
 ==================
 
-fuzzy_match
------------
-.. autofunction:: mycroft.util.parse.fuzzy_match
-
-match_one
----------
-.. autofunction:: mycroft.util.parse.match_one
-
-extract_datetime
----------
-.. autofunction:: mycroft.util.parse.extract_datetime
-
-extract_number
----------
-.. autofunction:: mycroft.util.parse.extract_number
+.. automodule:: mycroft.util.parse
+  :members:

doc/source/mycroft.util.rst

@@ -1,6 +1,14 @@
 mycroft.util package
 ====================
 
+The mycroft.util package includes functions for common operations such as
+playing audio files, parsting and creating natural text as well as many
+components used internally in Mycroft such as cache directory lookup,
+path resolution. etc.
+
+Below _some_ of the functions that are of interest to skill developers are
+listed.
+
 LOG
 ---
 .. autofunction:: mycroft.util.LOG

doc/source/mycroft.util.time.rst

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

mycroft/skills/core.py

@@ -482,8 +482,15 @@ def resting_screen_handler(name=None):
 #######################################################################
 class MycroftSkill:
     """
-    Abstract base class which provides common behaviour and parameters to all
-    Skills implementation.
+    Base class for mycroft skills providing common behaviour and parameters to
+    all Skill implementations.
+
+    For information on how to get started with creating mycroft skills see
+    https://https://mycroft.ai/documentation/skills/introduction-developing-skills/
+
+    Arguments:
+        name (str): skill name
+        bus (MycroftWebsocketClient): Optional bus connection
     """
 
     def __init__(self, name=None, bus=None, use_settings=True):

mycroft/util/format.py

@@ -13,6 +13,13 @@
 # limitations under the License.
 #
 
+"""
+The mycroft.util.format module provides various formatting functions for
+things like numbers, times, etc.
+
+The focus of these formatting functions is to create natural sounding speech
+and allow localization.
+"""
 from os.path import join
 
 from mycroft.util.lang import get_full_lang_code, get_primary_lang_code

mycroft/util/parse.py

@@ -14,6 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+"""
+The mycroft.util.parse module provides various parsing functions for
+things like numbers, times, durations etc.
+
+The focus of these parsing functions is to extract data from natural speech
+and to allow localization.
+"""
+
 from difflib import SequenceMatcher
 from mycroft.util.time import now_local
 from mycroft.util.lang import get_primary_lang_code