Add Doc Linting to CI (#294)

* add pydocstyle as dev dep

Co-authored-by: Jenny Fothergill

* only check jsondict.py & use numpy style

* path of least resistance is to check docstring style in style check section

* need to install pydocstyle

* adding myself to the list of contributors

* split linting of code and docs into mulitpul steps

* fix issues found with doc strings, TODO: fix place holder docstrings

* this should pass now!

* Docstring edits.

* Remove __str__ docstring.

* Update buffering docstring.

Co-Authored-By: Carl Simon Adorf <[email protected]>

* Update buffered docstring.

Co-Authored-By: Carl Simon Adorf <[email protected]>

* Ignore D105.

* Use stricter set of rules than numpy convention.

Co-authored-by: Bradley Dice <[email protected]>
Co-authored-by: Carl Simon Adorf <[email protected]>

.circleci/config.yml

@@ -17,11 +17,19 @@ jobs:
     steps:
       - checkout
       - run:
-          name: style-check
+          name: install-dependencies
+          command: |
+            pip install --progress-bar off --user -U flake8==3.7.1 pydocstyle==5.0.2
+
+      - run:
+          name: style-check-code
           command: |
-            pip install --progress-bar off --user -U flake8==3.7.9
             python -m flake8 --show-source .
 
+      - run:
+          name: style-check-doc-strings
+          command: |
+            pydocstyle
 
   linux-python-38: &linux-template
     docker:

contributors.yaml

@@ -84,4 +84,9 @@ contributors:
     family-names: Chandra
     given-names: Abhavya
     affiliation: "Indian Institute of Technology, Gandhinagar"
+  -
+    family-names: Henry
+    given-names: "Michael M."
+    affiliation: "Boise State University"
+    orcid: "https://orcid.org/0000-0002-3870-9993"
 ...

requirements-dev.txt

@@ -8,5 +8,6 @@ click>=7.0
 ruamel.yaml>=0.15.89
 pytest==5.3.4
 pytest-subtests==0.3.0
+pydocstyle==5.0.2
 pytest-cov==2.8.1
-pymongo==3.10.1
+pymongo==3.10.1

setup.cfg

@@ -14,6 +14,10 @@ python-tag = py3
 max-line-length = 100
 exclude = configobj,passlib,cite.py,conf.py
 
+[pydocstyle]
+match = jsondict.py
+ignore = D105, D107, D203, D213
+
 [coverage:run]
 source = signac
 omit =
@@ -32,4 +36,3 @@ filterwarnings =
 [bumpversion:file:CITATION.cff]
 
 [bumpversion:file:.zenodo.json]
-

signac/core/jsondict.py

@@ -1,7 +1,7 @@
 # Copyright (c) 2018 The Regents of the University of Michigan
 # All rights reserved.
 # This software is licensed under the BSD 3-Clause License.
-"Dict implementation with backend JSON file."
+"""Dict implementation with backend JSON file."""
 import os
 import sys
 import errno
@@ -31,7 +31,8 @@
 
 
 class BufferException(Error):
-    "An exception occured in buffered mode."
+    """An exception occured in buffered mode."""
+
     pass
 
 
@@ -44,6 +45,7 @@ class BufferedFileError(BufferException):
         mapped to a possible reason for the issue or None in case that it
         cannot be determined.
     """
+
     def __init__(self, files):
         self.files = files
 
@@ -52,7 +54,7 @@ def __str__(self):
 
 
 def _hash(blob):
-    "Calculate and return the md5 hash value for the file data."
+    """Calculate and return the md5 hash value for the file data."""
     if blob is not None:
         m = hashlib.md5()
         m.update(blob)
@@ -87,7 +89,7 @@ def _store_in_buffer(filename, blob, store_hash=False):
 
 
 def flush_all():
-    "Execute all deferred JSONDict write operations."
+    """Execute all deferred JSONDict write operations."""
     logger.debug("Flushing buffer...")
     issues = dict()
     while _JSONDICT_BUFFER:
@@ -117,17 +119,17 @@ def flush_all():
 
 
 def get_buffer_size():
-    "Returns the current maximum size of the read/write buffer."
+    """Return the current maximum size of the read/write buffer."""
     return _BUFFER_SIZE
 
 
 def get_buffer_load():
-    "Returns the current actual size of the read/write buffer."
+    """Return the current actual size of the read/write buffer."""
     return sum((sys.getsizeof(x) for x in _JSONDICT_BUFFER.values()))
 
 
 def in_buffered_mode():
-    "Return true if in buffered read/write mode."
+    """Return true if in buffered read/write mode."""
     return _BUFFERED_MODE > 0
 
 
@@ -235,6 +237,7 @@ class JSONDict(SyncedAttrDict):
     :param parent:
         A parent instance of JSONDict or None.
     """
+
     def __init__(self, filename=None, write_concern=False, parent=None):
         if (filename is None) == (parent is None):
             raise ValueError(
@@ -311,18 +314,29 @@ def reset(self, data):
 
     @contextmanager
     def buffered(self):
+        """Context manager for buffering read and write operations.
+
+        This context manager activates the "buffered" mode, which
+        means that all read operations are cached, and all write operations
+        are deferred until the buffered mode is deactivated.
+        """
         buffered_dict = BufferedSyncedAttrDict(self, parent=self)
         yield buffered_dict
         buffered_dict.flush()
 
 
 class BufferedSyncedAttrDict(SyncedAttrDict):
+    """Buffered :class:`~.SyncedAttrDict`.
+
+    Saves all changes in memory but does not write them to disk until :meth:`~.flush` is called.
+    """
 
-    def load(self):
+    def load(self):  # noqa: D102
         pass
 
-    def save(self):
+    def save(self):  # noqa: D102
         pass
 
     def flush(self):
+        """Save buffered changes to the underlying file."""
         self._parent._save(self())