Merge pull request #2805 from forslund/docs/filesystem

Docs/filesystem

doc/conf.py

@@ -66,7 +66,6 @@ autodoc_mock_imports = list(autodoc_mock_imports) + [
     'serial',
     'websocket',
     'speech_recognition',
-    'xdg',
     'yaml'
 ]
 

doc/requirements.txt

@@ -1,2 +1,3 @@
 sphinx>= 2.2.1
 sphinx_rtd_theme>=0.4.3
+pyxdg

doc/source/mycroft.filesystem.rst

@@ -0,0 +1,6 @@
+mycroft.filesystem
+==================
+
+.. autoclass:: mycroft.filesystem.FileSystemAccess
+    :members:
+

doc/source/mycroft.rst

@@ -56,6 +56,11 @@ removes_context decorator
 -------------------------
 .. autofunction:: mycroft.removes_context
 
+mycroft.filesystem
+==================
+
+.. toctree::
+    mycroft.filesystem
 
 mycroft.util
 ===============

mycroft/filesystem/__init__.py

@@ -17,13 +17,14 @@ from os.path import join, expanduser, isdir
 
 
 class FileSystemAccess:
-    """
+    """A class for providing access to the mycroft FS sandbox.
-    A class for providing access to the mycroft FS sandbox. Intended to be
+
-    attached to skills at initialization time to provide a skill-specific
+    Intended to be attached to skills at initialization time to provide a
-    namespace.
+    skill-specific namespace.
     """
 
     def __init__(self, path):
+        #: Member value containing the root path of the namespace
         self.path = self.__init_path(path)
 
     @staticmethod
@@ -37,19 +38,30 @@ class FileSystemAccess:
         return path
 
     def open(self, filename, mode):
-        """
+        """Open a file in the provided namespace.
+
         Get a handle to a file (with the provided mode) within the
         skill-specific namespace.
 
-        :param filename: a str representing a path relative to the namespace.
+        Parameters:
-            subdirs not currently supported.
+            filename (str): a path relative to the namespace.
+                      subdirs not currently supported.
 
-        :param mode: a file handle mode
+            mode (str): a file handle mode
 
-        :return: an open file handle.
+        Returns:
+            an open file handle.
         """
         file_path = join(self.path, filename)
         return open(file_path, mode)
 
     def exists(self, filename):
+        """Check if file exists in the namespace.
+
+        Arguments:
+            filename (str): a path relative to the namespace.
+                      subdirs not currently supported.
+        Returns:
+            bool: True if file exists, else False.
+        """
         return os.path.exists(join(self.path, filename))