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

Byron · Byron · commit 160081b9a7ca · 2010-06-29T18:28:31.000+02:00
diff --git a/doc/reference.rst b/doc/reference.rst
@@ -3,13 +3,6 @@
 API Reference
 =============
 
-Actor
------
-
-.. automodule:: git.actor
-   :members:
-   :undoc-members:
-
 Objects.Base
 ------------
 
@@ -45,12 +38,54 @@ Objects.Tree
    :members:
    :undoc-members:
 
+Objects.Functions
+-----------------
+
+.. automodule:: git.objects.fun
+   :members:
+   :undoc-members:
+
+Objects.Submodule
+-----------------
+
+.. automodule:: git.objects.submodule
+   :members:
+   :undoc-members:
+   
 Objects.Utils
 -------------
 
 .. automodule:: git.objects.utils
    :members:
    :undoc-members:
+
+Index.Base
+-------------
+
+.. automodule:: git.index.base
+   :members:
+   :undoc-members:
+
+Index.Functions
+---------------
+
+.. automodule:: git.index.fun
+   :members:
+   :undoc-members:
+   
+Index.Types
+-----------
+
+.. automodule:: git.index.typ
+   :members:
+   :undoc-members:
+   
+Index.Util
+-------------
+
+.. automodule:: git.index.util
+   :members:
+   :undoc-members:
    
 GitCmd
 ------
@@ -81,13 +116,6 @@ Errors
    :members:
    :undoc-members:
 
-Index
-------
-
-.. automodule:: git.index
-   :members:
-   :undoc-members:
-   
  
 Refs
 ----
@@ -110,13 +138,6 @@ Repo
    :members:
    :undoc-members:
 
-Stats
------
-
-.. automodule:: git.stats
-   :members:
-   :undoc-members:
-
 Utils
 -----
 
diff --git a/lib/git/cmd.py b/lib/git/cmd.py
@@ -272,7 +272,7 @@ def execute(self, command,
 			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
@@ -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 @@
 
 
 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 @@ def new(cls, repo, *tree_sha):
 
 		: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 @@ def from_tree(cls, repo, *treeish, **kwargs):
 		: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 @@ def from_tree(cls, repo, *treeish, **kwargs):
 			 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 @@ def remove(self, items, working_tree=False, **kwargs):
 			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 @@ def move(self, items, skip_errors=False, **kwargs):
 		: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 @@ def checkout(self, paths=None, force=False, fprogress=lambda *args: None, **kwar
 			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
@@ -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
@@ -78,10 +78,10 @@ def hexsha(self):
 	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
@@ -28,7 +28,8 @@ def _set_cache_(self, attr):
 
 	@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
@@ -182,11 +182,11 @@ def iter_items(cls, repo, rev, paths='', **kwargs):
 		
 	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
@@ -23,8 +23,8 @@
 __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 @@ def add(self, sha, mode, name, force=False):
 		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 @@ def blobs(self):
 
 	@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
@@ -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
diff --git a/lib/git/remote.py b/lib/git/remote.py
diff --git a/lib/git/utils.py b/lib/git/utils.py
