Updated and fixed sphinx API docs, which included one quick skim-through

11 files changed, 82 insertions, 52 deletions

diff --git a/lib/git/cmd.py b/lib/git/cmd.py
index d0f2a19e..e9c1ce24 100644
--- a/lib/git/cmd.py
+++ b/lib/git/cmd.py
@@ -272,7 +272,7 @@ class Git(object):
 			This merely is a workaround as data will be copied from the 
 			output pipe to the given output stream directly.
 			
-		:param **subprocess_kwargs:
+		:param subprocess_kwargs:
 			Keyword arguments to be passed to subprocess.Popen. Please note that 
 			some of the valid kwargs are already set by this method, the ones you 
 			specify may not be the same ones.
diff --git a/lib/git/index/base.py b/lib/git/index/base.py
index 03da52b7..1a8bee93 100644
--- a/lib/git/index/base.py
+++ b/lib/git/index/base.py
@@ -4,7 +4,7 @@
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 """Module containing Index implementation, allowing to perform all kinds of index
-manipulations such as querying and merging. """
+manipulations such as querying and merging."""
 import tempfile
 import os
 import sys
@@ -75,22 +75,26 @@ __all__ = ( 'IndexFile', 'CheckoutError' )
 
 
 class IndexFile(LazyMixin, diff.Diffable, Serializable):
-	"""Implements an Index that can be manipulated using a native implementation in
+	"""
+	Implements an Index that can be manipulated using a native implementation in
 	order to save git command function calls wherever possible.
-
+	
 	It provides custom merging facilities allowing to merge without actually changing
 	your index or your working tree. This way you can perform own test-merges based
 	on the index only without having to deal with the working copy. This is useful
 	in case of partial working trees.
 
 	``Entries``
+	
 	The index contains an entries dict whose keys are tuples of type IndexEntry
 	to facilitate access.
 
 	You may read the entries dict or manipulate it using IndexEntry instance, i.e.::
+	
 		index.entries[index.entry_key(index_entry_instance)] = index_entry_instance
-	Otherwise changes to it will be lost when changing the index using its methods.
-	"""
+	
+	Make sure you use index.write() once you are done manipulating the index directly
+	before operating on it using the git command"""
 	__slots__ = ("repo", "version", "entries", "_extension_data", "_file_path")
 	_VERSION = 2			# latest version we support
 	S_IFGITLINK = 0160000	# a submodule
@@ -250,7 +254,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 
 		:param repo: The repository treeish are located in.
 
-		:param *tree_sha:
+		:param tree_sha:
 			20 byte or 40 byte tree sha or tree objects 
 
 		:return:
@@ -276,7 +280,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 		:param repo:
 			The repository treeish are located in.
 
-		:param *treeish:
+		:param treeish:
 			One, two or three Tree Objects, Commits or 40 byte hexshas. The result
 			changes according to the amount of trees.
 			If 1 Tree is given, it will just be read into a new index
@@ -287,7 +291,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 			 being the common ancestor of tree 2 and tree 3. Tree 2 is the 'current' tree,
 			 tree 3 is the 'other' one
 
-		:param **kwargs:
+		:param kwargs:
 			Additional arguments passed to git-read-tree
 
 		:return:
@@ -790,7 +794,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 			removing the respective file. This may fail if there are uncommited changes
 			in it.
 
-		:param **kwargs:
+		:param kwargs:
 			Additional keyword arguments to be passed to git-rm, such
 			as 'r' to allow recurive removal of
 
@@ -828,7 +832,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 		:param skip_errors:
 			If True, errors such as ones resulting from missing source files will
 			be skpped.
-		:param **kwargs:
+		:param kwargs:
 			Additional arguments you would like to pass to git-mv, such as dry_run
 			or force.
 
@@ -924,7 +928,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 			explicit paths are given. Otherwise progress information will be send
 			prior and after a file has been checked out
 
-		:param **kwargs:
+		:param kwargs:
 			Additional arguments to be pasesd to git-checkout-index
 
 		:return:
diff --git a/lib/git/index/fun.py b/lib/git/index/fun.py
index ef950761..cc18c65c 100644
--- a/lib/git/index/fun.py
+++ b/lib/git/index/fun.py
@@ -51,8 +51,10 @@ def write_cache(entries, stream, extension_data=None, ShaStreamCls=IndexFileSHA1
 	:param entries: **sorted** list of entries
 	:param stream: stream to wrap into the AdapterStreamCls - it is used for
 		final output.
+		
 	:param ShaStreamCls: Type to use when writing to the stream. It produces a sha
 		while writing to it, before the data is passed on to the wrapped stream
+		
 	:param extension_data: any kind of data to write as a trailer, it must begin
 		a 4 byte identifier, followed by its size ( 4 bytes )"""
 	# wrap the stream into a compatible writer
@@ -103,7 +105,7 @@ def read_header(stream):
 
 def entry_key(*entry):
 	""":return: Key suitable to be used for the index.entries dictionary
-	:param *entry: One instance of type BaseIndexEntry or the path and the stage"""
+	:param entry: One instance of type BaseIndexEntry or the path and the stage"""
 	if len(entry) == 1:
 		return (entry[0].path, entry[0].stage)
 	else:
diff --git a/lib/git/index/typ.py b/lib/git/index/typ.py
index 7654b402..3a01cd65 100644
--- a/lib/git/index/typ.py
+++ b/lib/git/index/typ.py
@@ -78,10 +78,10 @@ class BaseIndexEntry(tuple):
 	def stage(self):
 		"""Stage of the entry, either:
 		
-			0 = default stage
-			1 = stage before a merge or common ancestor entry in case of a 3 way merge
-			2 = stage of entries from the 'left' side of the merge
-			3 = stage of entries from the right side of the merge
+			* 0 = default stage
+			* 1 = stage before a merge or common ancestor entry in case of a 3 way merge
+			* 2 = stage of entries from the 'left' side of the merge
+			* 3 = stage of entries from the right side of the merge
 		
 		:note: For more information, see http://www.kernel.org/pub/software/scm/git/docs/git-read-tree.html
 		"""
@@ -112,10 +112,10 @@ class IndexEntry(BaseIndexEntry):
 	See the properties for a mapping between names and tuple indices. """
 	@property
 	def ctime(self):
-		""":return:
-			Tuple(int_time_seconds_since_epoch, int_nano_seconds) of the
-			file's creation time
 		"""
+		:return:
+			Tuple(int_time_seconds_since_epoch, int_nano_seconds) of the
+			file's creation time"""
 		return unpack(">LL", self[4])
 
 	@property
diff --git a/lib/git/objects/blob.py b/lib/git/objects/blob.py
index 8263e9a2..d0ef54c7 100644
--- a/lib/git/objects/blob.py
+++ b/lib/git/objects/blob.py
@@ -28,7 +28,8 @@ class Blob(base.IndexObject):
 
 	@property
 	def mime_type(self):
-		""" :return:String describing the mime type of this file (based on the filename)
+		"""
+		:return: String describing the mime type of this file (based on the filename)
 		:note: Defaults to 'text/plain' in case the actual file type is unknown. """
 		guesses = None
 		if self.path:
diff --git a/lib/git/objects/commit.py b/lib/git/objects/commit.py
index f88bb0e8..11263e07 100644
--- a/lib/git/objects/commit.py
+++ b/lib/git/objects/commit.py
@@ -182,11 +182,11 @@ class Commit(base.Object, Iterable, Diffable, Traversable, Serializable):
 		
 	def iter_parents(self, paths='', **kwargs):
 		"""Iterate _all_ parents of this commit.
+		
 		:param paths:
 			Optional path or list of paths limiting the Commits to those that 
 			contain at least one of the paths
 		:param kwargs: All arguments allowed by git-rev-list
-			
 		:return: Iterator yielding Commit objects which are parents of self """
 		# skip ourselves
 		skip = kwargs.get("skip", 1)
diff --git a/lib/git/objects/tree.py b/lib/git/objects/tree.py
index 056d3da9..64725128 100644
--- a/lib/git/objects/tree.py
+++ b/lib/git/objects/tree.py
@@ -23,8 +23,8 @@ from gitdb.util import (
 __all__ = ("TreeModifier", "Tree")
 
 class TreeModifier(object):
-	"""A utility class providing methods to alter the underlying cache in a list-like
-	fashion.
+	"""A utility class providing methods to alter the underlying cache in a list-like fashion.
+	
 	Once all adjustments are complete, the _cache, which really is a refernce to 
 	the cache of a tree, will be sorted. Assuring it will be in a serializable state"""
 	__slots__ = '_cache'
@@ -57,6 +57,7 @@ class TreeModifier(object):
 		exists, nothing will be done, but a ValueError will be raised if the 
 		sha and mode of the existing item do not match the one you add, unless 
 		force is True
+		
 		:param sha: The 20 or 40 byte sha of the item to add
 		:param mode: int representing the stat compatible mode of the item
 		:param force: If True, an item with your name and information will overwrite
@@ -203,10 +204,11 @@ class Tree(IndexObject, diff.Diffable, utils.Traversable, utils.Serializable):
 
 	@property
 	def cache(self):
-		""":return: An object allowing to modify the internal cache. This can be used
-		to change the tree's contents. When done, make sure you call ``set_done``
-		on the tree modifier, or serialization behaviour will be incorrect.
-		See the ``TreeModifier`` for more information on how to alter the cache"""
+		"""
+		:return: An object allowing to modify the internal cache. This can be used
+			to change the tree's contents. When done, make sure you call ``set_done``
+			on the tree modifier, or serialization behaviour will be incorrect.
+			See the ``TreeModifier`` for more information on how to alter the cache"""
 		return TreeModifier(self._cache)
 
 	def traverse( self, predicate = lambda i,d: True,
diff --git a/lib/git/objects/utils.py b/lib/git/objects/utils.py
index c0ddd6e6..fd648f09 100644
--- a/lib/git/objects/utils.py
+++ b/lib/git/objects/utils.py
@@ -103,15 +103,15 @@ def verify_utctz(offset):
 def parse_date(string_date):
 	"""
 	Parse the given date as one of the following
+	
 		* Git internal format: timestamp offset
 		* RFC 2822: Thu, 07 Apr 2005 22:13:13 +0200. 
 		* ISO 8601 2005-04-07T22:13:13
-		 The T can be a space as well
+			The T can be a space as well
 		 
-	:return: Tuple(int(timestamp), int(offset), both in seconds since epoch
+	:return: Tuple(int(timestamp), int(offset)), both in seconds since epoch
 	:raise ValueError: If the format could not be understood
-	:note: Date can also be YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY 
-	"""
+	:note: Date can also be YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY"""
 	# git time
 	try:
 		if string_date.count(' ') == 1 and string_date.rfind(':') == -1:
diff --git a/lib/git/refs.py b/lib/git/refs.py
index 8258ca8d..c8d67d3f 100644
--- a/lib/git/refs.py
+++ b/lib/git/refs.py
@@ -64,7 +64,8 @@ class SymbolicReference(object):
 		
 	@property
 	def name(self):
-		""":return:
+		"""
+		:return:
 			In case of symbolic references, the shortest assumable name 
 			is the path itself."""
 		return self.path	
@@ -244,7 +245,8 @@ class SymbolicReference(object):
 		
 	@property
 	def is_detached(self):
-		""":return:
+		"""
+		:return:
 			True if we are a detached reference, hence we point to a specific commit
 			instead to another reference"""
 		try:
@@ -256,8 +258,9 @@ class SymbolicReference(object):
 
 	@classmethod
 	def to_full_path(cls, path):
-		""":return: string with a full path name which can be used to initialize 
-		a Reference instance, for instance by using ``Reference.from_path``"""
+		"""
+		:return: string with a full path name which can be used to initialize 
+			a Reference instance, for instance by using ``Reference.from_path``"""
 		if isinstance(path, SymbolicReference):
 			path = path.path
 		full_ref_path = path
@@ -369,6 +372,7 @@ class SymbolicReference(object):
 		:raise OSError:
 			If a (Symbolic)Reference with the same name but different contents
 			already exists.
+		
 		:note: This does not alter the current HEAD, index or Working Tree"""
 		return cls._create(repo, path, False, reference, force)
 	
@@ -563,17 +567,21 @@ class Reference(SymbolicReference, LazyMixin, Iterable):
 	@classmethod
 	def create(cls, repo, path, commit='HEAD', force=False ):
 		"""Create a new reference.
+		
 		:param repo: Repository to create the reference in 
 		:param path:
 			The relative path of the reference, i.e. 'new_branch' or 
 			feature/feature1. The path prefix 'refs/' is implied if not 
 			given explicitly
+			
 		:param commit:
 			Commit to which the new reference should point, defaults to the 
 			current HEAD
+			
 		:param force:
 			if True, force creation even if a reference with that  name already exists.
 			Raise OSError otherwise
+			
 		:return: Newly created Reference
 			
 		:note: This does not alter the current HEAD, index or Working Tree"""
@@ -666,15 +674,18 @@ class Head(Reference):
 		:param path:
 			The name or path of the head, i.e. 'new_branch' or 
 			feature/feature1. The prefix refs/heads is implied.
+			
 		:param commit:
 			Commit to which the new head should point, defaults to the 
 			current HEAD
+			
 		:param force:
 			if True, force creation even if branch with that  name already exists.
 			
-		:param **kwargs:
+		:param kwargs:
 			Additional keyword arguments to be passed to git-branch, i.e.
 			track, no-track, l
+			
 		:return: Newly created Head
 		:note: This does not alter the current HEAD, index or Working Tree"""
 		if cls is not Head:
@@ -734,7 +745,7 @@ class Head(Reference):
 			If True, changes to the index and the working tree will be discarded.
 			If False, GitCommandError will be raised in that situation.
 			
-		:param **kwargs:
+		:param kwargs:
 			Additional keyword arguments to be passed to git checkout, i.e.
 			b='new_branch' to create a new branch at the given spot.
 		
@@ -818,7 +829,7 @@ class TagReference(Reference):
 		:param force:
 			If True, to force creation of a tag even though that tag already exists.
 			
-		:param **kwargs:
+		:param kwargs:
 			Additional keyword arguments to be passed to git-tag
 			
 		:return: A new TagReference"""
diff --git a/lib/git/remote.py b/lib/git/remote.py
index 9c46a027..1558eeb3 100644
--- a/lib/git/remote.py
+++ b/lib/git/remote.py
@@ -52,8 +52,10 @@ class _SectionConstraint(object):
 		
 		
 class RemoteProgress(object):
-	"""Handler providing an interface to parse progress information emitted by git-push
-	and git-fetch and to dispatch callbacks allowing subclasses to react to the progress."""
+	"""
+	Handler providing an interface to parse progress information emitted by git-push
+	and git-fetch and to dispatch callbacks allowing subclasses to react to the progress.
+	"""
 	BEGIN, END, COUNTING, COMPRESSING, WRITING =  [ 1 << x for x in range(5) ]
 	STAGE_MASK = BEGIN|END
 	OP_MASK = COUNTING|COMPRESSING|WRITING
@@ -168,7 +170,8 @@ class RemoteProgress(object):
 		
 		
 class PushInfo(object):
-	"""Carries information about the result of a push operation of a single head::
+	"""
+	Carries information about the result of a push operation of a single head::
 	
 		info = remote.push()[0]
 		info.flags			# bitflags providing more information about the result
@@ -179,7 +182,8 @@ class PushInfo(object):
 						# the remote_ref_string. It can be a TagReference as well.
 		info.old_commit # commit at which the remote_ref was standing before we pushed
 						# it to local_ref.commit. Will be None if an error was indicated
-		info.summary	# summary line providing human readable english text about the push"""
+		info.summary	# summary line providing human readable english text about the push
+		"""
 	__slots__ = ('local_ref', 'remote_ref_string', 'flags', 'old_commit', '_remote', 'summary')
 	
 	NEW_TAG, NEW_HEAD, NO_MATCH, REJECTED, REMOTE_REJECTED, REMOTE_FAILURE, DELETED, \
@@ -201,7 +205,8 @@ class PushInfo(object):
 		
 	@property
 	def remote_ref(self):
-		""":return:
+		"""
+		:return:
 			Remote Reference or TagReference in the local repository corresponding 
 			to the remote_ref_string kept in this instance."""
 		# translate heads to a local remote, tags stay as they are
@@ -266,7 +271,8 @@ class PushInfo(object):
 		
 
 class FetchInfo(object):
-	"""Carries information about the results of a fetch operation of a single head::
+	"""
+	Carries information about the results of a fetch operation of a single head::
 	
 	 info = remote.fetch()[0]
 	 info.ref			# Symbolic Reference or RemoteReference to the changed 
@@ -276,7 +282,8 @@ class FetchInfo(object):
 						# is 0 if ref is SymbolicReference
 	 info.note			# additional notes given by git-fetch intended for the user
 	 info.old_commit	# if info.flags & info.FORCED_UPDATE|info.FAST_FORWARD, 
-						# field is set to the previous location of ref, otherwise None"""
+						# field is set to the previous location of ref, otherwise None
+	"""
 	__slots__ = ('ref','old_commit', 'flags', 'note')
 	
 	NEW_TAG, NEW_HEAD, HEAD_UPTODATE, TAG_UPDATE, REJECTED, FORCED_UPDATE, \
@@ -501,7 +508,7 @@ class Remote(LazyMixin, Iterable):
 		: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:
+		:param kwargs:
 			Additional arguments to be passed to the git-remote add command
 			
 		:return: New Remote instance
@@ -644,7 +651,7 @@ class Remote(LazyMixin, Iterable):
 			
 			Taken from the git manual
 		:param progress: See 'push' method
-		:param **kwargs: Additional arguments to be passed to git-fetch
+		:param kwargs: Additional arguments to be passed to git-fetch
 		:return:
 			IterableList(FetchInfo, ...) list of FetchInfo instances providing detailed 
 			information about the fetch results
@@ -675,7 +682,7 @@ class Remote(LazyMixin, Iterable):
 			progress information until the method returns.
 			If None, progress information will be discarded
 		
-		:param **kwargs: Additional arguments to be passed to git-push
+		:param kwargs: Additional arguments to be passed to git-push
 		:return:
 			IterableList(PushInfo, ...) iterable list of PushInfo instances, each 
 			one informing about an individual head which had been updated on the remote 
diff --git a/lib/git/utils.py b/lib/git/utils.py
index e49fcc2a..54c3414e 100644
--- a/lib/git/utils.py
+++ b/lib/git/utils.py
@@ -269,7 +269,8 @@ class BlockingLockFile(LockFile):
 	
 
 class IterableList(list):
-	"""List of iterable objects allowing to query an object by id or by named index::
+	"""
+	List of iterable objects allowing to query an object by id or by named index::
 	 
 	 heads = repo.heads
 	 heads.master
@@ -317,11 +318,13 @@ class Iterable(object):
 	
 	@classmethod
 	def list_items(cls, repo, *args, **kwargs):
-		"""Find all items of this type - subclasses can specify args and kwargs differently.
+		"""
+		Find all items of this type - subclasses can specify args and kwargs differently.
 		If no args are given, subclasses are obliged to return all items if no additional 
 		arguments arg given.
 		
-		:note: Favor the iter_items method as it will 
+		:note: Favor the iter_items method as it will
+		
 		:return:list(Item,...) list of item instances"""
 		out_list = IterableList( cls._id_attribute_ )
 		out_list.extend(cls.iter_items(repo, *args, **kwargs))