Another major refactoring, add documentation

Move all useful functions to the qmk module and use the cli subcommand
as a wrapper around it.
Add both inline comments and documentation.

lib/python/qmk/path.py

@@ -5,6 +5,7 @@ import os
 
 from qmk.errors import NoSuchKeyboardError
 
+from bs4 import UnicodeDammit
 
 def keymap(keyboard):
     """Locate the correct directory for storing a keymap.
@@ -33,3 +34,20 @@ def normpath(path):
         return os.path.normpath(path)
 
     return os.path.normpath(os.path.join(os.environ['ORIG_CWD'], path))
+
+def unicode_text(filename):
+    """Returns the contents of filename as a UTF-8 string. Tries to DTRT when it comes to encoding.
+    """
+    with open(filename, "rb") as fd:
+        text = UnicodeDammit(fd.read())
+
+    if text.contains_replacement_characters:
+        log_warning("%s: Could not determine file encoding, some characters were replaced." % (filename,))
+
+    return text.unicode_markup or ""
+
+
+def unicode_lines(filename):
+    """Returns the contents of filename as a UTF-8 string. Tries to DTRT when it comes to encoding.
+    """
+    return unicode_text(filename).split("\n")