Docs: Add docstrings to everything and do not show inherrited members

dev_requirements.txt

@@ -1,5 +1,4 @@
 -e .[all]
 -e git+https://github.com/JelteF/sphinx.git@better-autodoc-skip-member#egg=sphinx-dev
 -e git+https://github.com/JelteF/sphinx_rtd_theme.git@master#egg=sphinx-rtd-theme
--e git+https://github.com/JelteF/pep257.git@e6187411646c0f324670dbc282bc1200b50e5f68#egg=pep257
 -e git+https://github.com/PyCQA/pep8.git@4dc42d842274ba27d2724e76eb83ff69e7db226f#egg=pep8-master

docs/conf.py

@@ -92,7 +92,7 @@
 #today_fmt = '%B %d, %Y'
 
 autodoc_member_order = 'bysource'
-autodoc_default_flags = ['inherited-members']
+autodoc_default_flags = []
 autoclass_content = 'both'
 
 

easyfuse/filesystem.py

@@ -15,26 +15,12 @@
 
 
 class BaseEntry(EntryAttributes):
-    """The base class that all filesystem classes should subclass."""
+    """The base class that all filesystem classes should subclass.
 
-    _prints = ('path', 'inode', )
-
-    _dirty = False
-
-    lookup_count = 0
-    deleted = False
-
-    @property
-    def inode(self):
-        """The inode number.
-
-        This is simply an alias for `st_ino` with a clearer name.
-        """
-        return self.st_ino
-
-    @inode.setter
-    def inode(self, value):
-        self.st_ino = value
+    This is a subclass `llfuse.EntryAttributes` and its attributes that are
+    required to have a working filesystem are implemented. Most others are not
+    actually implemented currently.
+    """
 
     def __init__(self, name, fs, parent, *, inode=None):
         """
@@ -46,7 +32,7 @@ def __init__(self, name, fs, parent, *, inode=None):
             This stores the mapping from an inode number to a `~.File` or
             `~.Directory` object. The newly created `BaseEntry` will be added
             to this as well. It should most likely be the ``fs`` attribute of
-            the instance that made created this instance.
+            the instance that creates this entry.
 
         parent: `~.Directory`
             The filesystem parent of this
@@ -99,24 +85,37 @@ def __repr__(self):
         string += ')>'
         return string
 
-    def generate_inode_number(self):
-        """Generate a unique inode number.
+    _prints = ('path', 'inode', )
 
-        By default this is done by taking part of the result of uuid4. This
-        method can be overridden if another method is preferred.
-        """
+    _dirty = False
 
-        inode = uuid4().int & (1 << 32)-1
-        while inode in self.fs:
-            inode = uuid4().int & (1 << 32)-1
-        return inode
+    #: The amount of times this entry has been looked up by the kernel.
+    #: This is increased by a couple of methodes called on `~.Operations` by
+    #: normal filesystem operations.
+    lookup_count = 0
 
-    def update_modified(self):
-        """Update the modified time to the current time."""
-        self.modified = time.time()
+    #: Indicates if the entry has been deleted.
+    deleted = False
+
+    @property
+    def inode(self):
+        """The inode number.
+
+        This is simply an alias for `~.llfuse.EntryAttributes.st_ino` with a
+        clearer name.
+        """
+        return self.st_ino
+
+    @inode.setter
+    def inode(self, value):
+        self.st_ino = value
 
     @property
     def modified(self):
+        """The moment of last modification of the entry.
+
+        This is measured in seconds since the UNIX epoch.
+        """
         return self.st_mtime_ns / 10**9
 
     @modified.setter
@@ -126,6 +125,17 @@ def modified(self, value):
         self.st_ctime_ns = value
         self.st_mtime_ns = value
 
+    @property
+    def dirty(self):
+        """Indicates if this entry has been changed but not synced."""
+        return self._dirty
+
+    @dirty.setter
+    def dirty(self, value):
+        self._dirty = value
+        if value is True and self.parent is not None:
+            self.parent.dirty_children = True
+
     @property
     def path(self):
         """The full path of this entry from the mount directory."""
@@ -146,10 +156,27 @@ def depth(self):
         """
         return len(self.parents)
 
+    def generate_inode_number(self):
+        """Generate a unique inode number.
+
+        By default this is done by taking part of the result of uuid4. This
+        method can be overridden if another method is preferred.
+        """
+
+        inode = uuid4().int & (1 << 32)-1
+        while inode in self.fs:
+            inode = uuid4().int & (1 << 32)-1
+        return inode
+
+    def update_modified(self):
+        """Update the modified time to the current time."""
+        self.modified = time.time()
+
     def delete(self):
-        """Dummy delete method.
+        """Basic deletion operations.
 
-        Override this when code needs to be executed on deletion.
+        Override this when code needs to be executed on deletion. Keep calling
+        this one by using `super` though, since it does some internal things.
         """
         logging.info('Deleting %s', self.path)
         self.deleted = True
@@ -161,17 +188,8 @@ def save(self):
         """
         logging.info('Saving %s', self.path)
 
-    @property
-    def dirty(self):
-        return self._dirty
-
-    @dirty.setter
-    def dirty(self, value):
-        self._dirty = value
-        if value is True and self.parent is not None:
-            self.parent.dirty_children = True
-
     def fsync(self):
+        """Save the entry if it is `~.BaseEntry.dirty`."""
         if self.dirty:
             with _convert_error_to_fuse_error('saving', self.path):
                 self.save()
@@ -205,6 +223,7 @@ def __init__(self, *args, **kwargs):
 
     @property
     def content(self):
+        """The content of this file in bytes."""
         if self._content is None:
             with _convert_error_to_fuse_error('refreshing content of',
                                               self.path):
@@ -253,6 +272,26 @@ def children(self):
                 self.refresh_children()
         return self._children
 
+    @property
+    def path(self):
+        """The full path of this directory from the mount directory."""
+        return super().path + '/'
+
+    @property
+    def dirty_children(self):
+        """Indicates if the `~.children` need to be synced.
+
+        It is set to `True` if a child of this directory is `~.BaseEntry.dirty`
+        or has `~.dirty_children` itself.
+        """
+        return self._dirty_children
+
+    @dirty_children.setter
+    def dirty_children(self, value):
+        self._dirty_children = value
+        if value is True and self.parent is not None:
+            self.parent.dirty_children = True
+
     def refresh_children(self):
         """Initialize children as an empty `dict`.
 
@@ -262,26 +301,16 @@ def refresh_children(self):
         """
         self._children = {}
 
-    @property
-    def path(self):
-        """The full path of this directory from the mount directory."""
-        return super().path + '/'
-
     def fsync(self):
+        """Save this entry and `~.BaseEntry.fsync` its children.
+
+        Saving is only done if this entry is `~.BaseEntry.dirty` and syncing
+        the children is only done if `~.dirty_children` is `True`.
+        """
         super().fsync()
 
         if self.dirty_children:
             for c in self.children.values():
                 c.fsync()
 
             self.dirty_children = False
-
-    @property
-    def dirty_children(self):
-        return self._dirty_children
-
-    @dirty_children.setter
-    def dirty_children(self, value):
-        self._dirty_children = value
-        if value is True and self.parent is not None:
-            self.parent.dirty_children = True

easyfuse/operations.py

@@ -230,7 +230,8 @@ def get_file_class(self, name):
     def read(self, fh, offset, length):
         """A basic implementation of the `llfuse.Operations.read` method.
 
-        It reads bytes from the ``content`` attribute of the selected entry.
+        It reads bytes from the `~.File.content` attribute of the selected
+        `~.File`.
         """
         logging.debug('read %s %s %s', fh, offset, length)
         return self.fs[fh].content[offset: offset + length]

setup.cfg

@@ -4,7 +4,12 @@ description-file = README.rst
 # Not everything has to be documented, but everything that is documented should
 # be documented well. Furthermore, a blank line after a doc string should
 # always be okay and spaces around every arithmetic operator can make stuff
-# less reabable. Raw strings are not required since linebreaks have to be
+# less reabable.
+# Raw strings are not required since linebreaks have to be
 # entered for napoleon so it can handle long types.
+#
 [flake8]
-ignore = D1,D202,D203,E226,D212,D403,D404
+ignore = D1,D202,D203,E226,D212
+putty-ignore =
+    /def __init__/ : +D205,D400,D401
+    /def dirty(_children)?/ : +D401

setup.py

@@ -21,7 +21,8 @@
 
 extras = {
     'docs': ['sphinx'],
-    'testing': ['flake8', 'pep8-naming', 'flake8_docstrings', 'nose'],
+    'testing': ['flake8', 'pep8-naming', 'flake8_docstrings', 'flake8-putty',
+                'nose'],
     'convert_to_py2': ['3to2', 'future'],
 }
 

testall.sh

@@ -75,14 +75,14 @@ fi
 # if [ "$clean" = 'TRUE' ]; then
 #     rm *.pdf *.log *.aux *.tex *.fls *.fdb_latexmk
 # fi
-#
-#
-# if [ "$python_version" = '3' -a "$nodoc" != 'TRUE' ]; then
-#     echo -e '\e[32mChecking for errors in docs and docstrings\e[0m'
-#     cd docs
-#     ./create_doc_files.sh -p $python
-#     make clean
-#     if ! $python $(which sphinx-build) -b html -d build/doctrees/ source build/html -nW; then
-#         exit 1
-#     fi
-# fi
+
+
+if [ "$python_version" = '3' -a "$nodoc" != 'TRUE' ]; then
+    echo -e '\e[32mChecking for errors in docs and docstrings\e[0m'
+    cd docs
+    ./create_doc_files.sh -p $python
+    make clean
+    if ! $python $(which sphinx-build) -b html -d _build/doctrees/ . _build/html -nW; then
+        exit 1
+    fi
+fi