Fixed some doc strings to build correctly with sphinx

Fixes gitpython-developers#7

[ci skip]

Author: Byron

git/cmd.py

@@ -769,10 +769,10 @@ def get_object_data(self, ref):
         return (hexsha, typename, size, data)
 
     def stream_object_data(self, ref):
-        """As get_object_header, but returns the data as a stream
+        """ As get_object_header, but returns the data as a stream
+
         :return: (hexsha, type_string, size_as_int, stream)
-        :note: This method is not threadsafe, you need one independent  Command instance
-            per thread to be safe !"""
+        :note: This method is not threadsafe, you need one independent Command instance per thread to be safe !"""
         cmd = self._get_persistent_cmd("cat_file_all", "cat_file", batch=True)
         hexsha, typename, size = self.__get_object_header(cmd, ref)
         return (hexsha, typename, size, self.CatFileContentStream(size, cmd.stdout))

git/index/fun.py

@@ -166,11 +166,10 @@ def entry_key(*entry):
 def read_cache(stream):
     """Read a cache file from the given stream
     :return: tuple(version, entries_dict, extension_data, content_sha)
-        * version is the integer version number
-        * entries dict is a dictionary which maps IndexEntry instances to a path
-            at a stage
-        * extension_data is '' or 4 bytes of type + 4 bytes of size + size bytes
-        * content_sha is a 20 byte sha on all cache file contents"""
+    * version is the integer version number
+    * entries dict is a dictionary which maps IndexEntry instances to a path at a stage
+    * extension_data is '' or 4 bytes of type + 4 bytes of size + size bytes
+    * content_sha is a 20 byte sha on all cache file contents"""
     version, num_entries = read_header(stream)
     count = 0
     entries = dict()

git/refs/head.py

@@ -114,6 +114,7 @@ class Head(Reference):
     @classmethod
     def delete(cls, repo, *heads, **kwargs):
         """Delete the given heads
+
         :param force:
             If True, the heads will be deleted even if they are not yet merged into
             the main development stream.

git/refs/remote.py

@@ -25,7 +25,8 @@ def iter_items(cls, repo, common_path=None, remote=None):
 
     @classmethod
     def delete(cls, repo, *refs, **kwargs):
-        """Delete the given remote references.
+        """Delete the given remote references
+
         :note:
             kwargs are given for compatability with the base class method as we
             should not narrow the signature."""

git/remote.py

@@ -398,8 +398,9 @@ def __hash__(self):
         return hash(self.name)
 
     def exists(self):
-        """:return: True if this is a valid, existing remote.
-        Valid remotes have an entry in the repository's configuration"""
+        """
+        :return: True if this is a valid, existing remote.
+            Valid remotes have an entry in the repository's configuration"""
         try:
             self.config_reader.get('url')
             return True
@@ -429,7 +430,7 @@ def refs(self):
         :return:
             IterableList of RemoteReference objects. It is prefixed, allowing
             you to omit the remote path portion, i.e.::
-             remote.refs.master # yields RemoteReference('/refs/remotes/origin/master')"""
+            remote.refs.master # yields RemoteReference('/refs/remotes/origin/master')"""
         out_refs = IterableList(RemoteReference._id_attribute_, "%s/" % self.name)
         out_refs.extend(RemoteReference.list_items(self.repo, remote=self.name))
         assert out_refs, "Remote %s did not have any references" % self.name
@@ -463,11 +464,8 @@ def create(cls, repo, name, url, **kwargs):
         :param repo: Repository instance that is to receive the new remote
         :param name: Desired name of the remote
         :param url: URL which corresponds to the remote's name
-        :param kwargs:
-            Additional arguments to be passed to the git-remote add command
-
+        :param kwargs: Additional arguments to be passed to the git-remote add command
         :return: New Remote instance
-
         :raise GitCommandError: in case an origin with that name already exists"""
         repo.git.remote("add", name, url, **kwargs)
         return cls(repo, name)

git/repo/base.py

@@ -461,7 +461,8 @@ def iter_commits(self, rev=None, paths='', **kwargs):
         return Commit.iter_items(self, rev, paths, **kwargs)
 
     def merge_base(self, *rev, **kwargs):
-        """Find the closest common ancestor for the given revision (e.g. Commits, Tags, References, etc).
+        """Find the closest common ancestor for the given revision (e.g. Commits, Tags, References, etc)
+
         :param rev: At least two revs to find the common ancestor for.
         :param kwargs: Additional arguments to be passed to the repo.git.merge_base() command which does all the work.
         :return: A list of Commit objects. If --all was not specified as kwarg, the list will have at max one Commit,
@@ -814,16 +815,13 @@ def _clone(cls, git, url, path, odb_default_type, progress, **kwargs):
 
     def clone(self, path, progress=None, **kwargs):
         """Create a clone from this repository.
-        :param path:
-            is the full path of the new repo (traditionally ends with ./<name>.git).
 
+        :param path: is the full path of the new repo (traditionally ends with ./<name>.git).
         :param progress: See 'git.remote.Remote.push'.
-
         :param kwargs:
-            odbt = ObjectDatabase Type, allowing to determine the object database
-            implementation used by the returned Repo instance
-
-            All remaining keyword arguments are given to the git-clone command
+            * odbt = ObjectDatabase Type, allowing to determine the object database
+              implementation used by the returned Repo instance
+            * All remaining keyword arguments are given to the git-clone command
 
         :return: ``git.Repo`` (the newly cloned repo)"""
         return self._clone(self.git, self.git_dir, path, type(self.odb), progress, **kwargs)
@@ -840,16 +838,16 @@ def clone_from(cls, url, to_path, progress=None, **kwargs):
 
     def archive(self, ostream, treeish=None, prefix=None, **kwargs):
         """Archive the tree at the given revision.
+
         :parm ostream: file compatible stream object to which the archive will be written as bytes
         :parm treeish: is the treeish name/id, defaults to active branch
         :parm prefix: is the optional prefix to prepend to each filename in the archive
-        :parm kwargs:
-            Additional arguments passed to git-archive
-            NOTE: Use the 'format' argument to define the kind of format. Use
-            specialized ostreams to write any format supported by python.
+        :parm kwargs: Additional arguments passed to git-archive
 
-            You may specify the special 'path' keyword, which may either be a repository-relative
-            path to a directory or file to place into the archive, or a list or tuple of multipe paths.
+            * Use the 'format' argument to define the kind of format. Use
+              specialized ostreams to write any format supported by python.
+            * You may specify the special **path** keyword, which may either be a repository-relative
+              path to a directory or file to place into the archive, or a list or tuple of multipe paths.
 
         :raise GitCommandError: in case something went wrong
         :return: self"""

git/util.py

@@ -40,6 +40,7 @@
 
 def rmtree(path):
     """Remove the given recursively.
+
     :note: we use shutil rmtree but adjust its behaviour to see whether files that
         couldn't be deleted are read-only. Windows will not remove them in that case"""
     def onerror(func, path, exc_info):
@@ -251,8 +252,10 @@ def _parse_progress_line(self, line):
         return failed_lines
 
     def new_message_handler(self):
-        """:return: a progress handler suitable for handle_process_output(), passing lines on to this Progress
-        handler in a suitable format"""
+        """
+        :return:
+            a progress handler suitable for handle_process_output(), passing lines on to this Progress
+            handler in a suitable format"""
         def handler(line):
             return self._parse_progress_line(line.rstrip())
         # end