Docstring/PEP 257 fixes for the vcs_support app (#2823)

Author: alexwlchan

readthedocs/vcs_support/backends/git.py

@@ -131,7 +131,10 @@ def branches(self):
 
     def parse_branches(self, data):
         """
-        Parse output of git branch -r, eg:
+        Parse output of git branch -r
+
+        e.g.:
+
               origin/2.0.X
               origin/HEAD -> origin/master
               origin/develop

readthedocs/vcs_support/backends/hg.py

@@ -49,11 +49,7 @@ def branches(self):
         return self.parse_branches(stdout)
 
     def parse_branches(self, data):
-        """
-        stable
-        default
-        """
-
+        """Stable / default"""
         names = [name.lstrip() for name in data.splitlines()]
         return [VCSVersion(self, name, name) for name in names if name]
 

readthedocs/vcs_support/base.py

@@ -10,6 +10,7 @@
 
 
 class VCSVersion(object):
+
     """
     Represents a Version (tag or branch) in a VCS.
 
@@ -18,6 +19,7 @@ class VCSVersion(object):
     It can act as a context manager to temporarily switch to this tag (eg to
     build docs for this tag).
     """
+
     def __init__(self, repository, identifier, verbose_name):
         self.repository = repository
         self.identifier = identifier
@@ -30,23 +32,23 @@ def __repr__(self):
 
 class VCSProject(namedtuple("VCSProject",
                             "name default_branch working_dir repo_url")):
+
     """Transient object to encapsulate a projects stuff"""
+
     pass
 
 
 class BaseCLI(object):
-    """
-    Helper class for CLI-heavy classes.
-    """
+
+    """Helper class for CLI-heavy classes."""
+
     log_tmpl = u'VCS[{name}:{ident}]: {args}'
 
     def __call__(self, *args):
         return self.run(args)
 
     def run(self, *args):
-        """
-        :param bits: list of command and args. See `subprocess` docs
-        """
+        """:param bits: list of command and args. See `subprocess` docs"""
         process = subprocess.Popen(args, stdout=subprocess.PIPE,
                                    stderr=subprocess.PIPE,
                                    cwd=self.working_dir, shell=False,
@@ -74,10 +76,13 @@ def env(self):
 
 
 class BaseVCS(BaseCLI):
+
     """
     Base for VCS Classes.
+
     Built on top of the BaseCLI.
     """
+
     supports_tags = False  # Whether this VCS supports tags or not.
     supports_branches = False  # Whether this VCS supports branches or not.
 
@@ -96,12 +101,14 @@ def check_working_dir(self):
             os.makedirs(self.working_dir)
 
     def make_clean_working_dir(self):
-        "Ensures that the working dir exists and is empty"
+        """Ensures that the working dir exists and is empty"""
         shutil.rmtree(self.working_dir, ignore_errors=True)
         self.check_working_dir()
 
     def update(self):
         """
+        Update a local copy of the repository in self.working_dir.
+
         If self.working_dir is already a valid local copy of the repository,
         update the repository, else create a new local copy of the repository.
         """
@@ -116,24 +123,24 @@ def update(self):
     @property
     def tags(self):
         """
-        Returns a list of VCSVersion objects. See VCSVersion for more
-        information.
+        Returns a list of VCSVersion objects.
+
+        See VCSVersion for more information.
         """
         raise NotImplementedError
 
     @property
     def branches(self):
         """
-        Returns a list of VCSVersion objects. See VCSVersion for more
-        information.
+        Returns a list of VCSVersion objects.
+
+        See VCSVersion for more information.
         """
         raise NotImplementedError
 
     @property
     def commit(self):
-        """
-        Returns a string representing the current commit.
-        """
+        """Returns a string representing the current commit."""
         raise NotImplementedError
 
     def checkout(self, identifier=None):

readthedocs/vcs_support/utils.py

@@ -11,6 +11,7 @@ class LockTimeout(Exception):
 
 
 class Lock(object):
+
     """
     A simple file based lock with timeout
 
@@ -58,6 +59,7 @@ def __exit__(self, exc, value, tb):
 
 
 class NonBlockingLock(object):
+
     """
     Instead of waiting for a lock, depending on the lock file age, either
     acquire it immediately or throw LockTimeout