Added auto-doc api reference and fixed plenty of docstrings

Author: Byron

db/base.py

@@ -90,7 +90,9 @@ def __init__(self, *args, **kwargs):
 
 	#{ Edit Interface
 	def set_ostream(self, stream):
-		"""Adjusts the stream to which all data should be sent when storing new objects
+		"""
+		Adjusts the stream to which all data should be sent when storing new objects
+		
 		:param stream: if not None, the stream to use, if None the default stream
 			will be used.
 		:return: previously installed stream, or None if there was no override
@@ -100,30 +102,36 @@ def set_ostream(self, stream):
 		return cstream
 
 	def ostream(self):
-		""":return: overridden output stream this instance will write to, or None
+		"""
+		:return: overridden output stream this instance will write to, or None
 			if it will write to the default stream"""
 		return self._ostream
 
 	def store(self, istream):
-		"""Create a new object in the database
+		"""
+		Create a new object in the database
 		:return: the input istream object with its sha set to its corresponding value
+		
 		:param istream: IStream compatible instance. If its sha is already set 
 			to a value, the object will just be stored in the our database format, 
 			in which case the input stream is expected to be in object format ( header + contents ).
 		:raise IOError: if data could not be written"""
 		raise NotImplementedError("To be implemented in subclass")
 
 	def store_async(self, reader):
-		"""Create multiple new objects in the database asynchronously. The method will 
+		"""
+		Create multiple new objects in the database asynchronously. The method will 
 		return right away, returning an output channel which receives the results as 
 		they are computed.
 		
 		:return: Channel yielding your IStream which served as input, in any order.
 			The IStreams sha will be set to the sha it received during the process, 
 			or its error attribute will be set to the exception informing about the error.
+			
 		:param reader: async.Reader yielding IStream instances.
 			The same instances will be used in the output channel as were received
 			in by the Reader.
+		
 		:note:As some ODB implementations implement this operation atomic, they might 
 			abort the whole operation if one item could not be processed. Hence check how 
 			many items have actually been produced."""
@@ -167,8 +175,10 @@ class CachingDB(object):
 
 	#{ Interface 
 	def update_cache(self, force=False):
-		"""Call this method if the underlying data changed to trigger an update
+		"""
+		Call this method if the underlying data changed to trigger an update
 		of the internal caching structures.
+		
 		:param force: if True, the update must be performed. Otherwise the implementation
 			may decide not to perform an update if it thinks nothing has changed.
 		:return: True if an update was performed as something change indeed"""

db/pack.py

@@ -128,8 +128,10 @@ def store_async(self, reader):
 	#{ Interface 
 
 	def update_cache(self, force=False):
-		"""Update our cache with the acutally existing packs on disk. Add new ones, 
+		"""
+		Update our cache with the acutally existing packs on disk. Add new ones, 
 		and remove deleted ones. We keep the unchanged ones
+		
 		:param force: If True, the cache will be updated even though the directory
 			does not appear to have changed according to its modification timestamp.
 		:return: True if the packs have been updated so there is new information, 

doc/.gitignore

@@ -0,0 +1 @@
+build/

doc/source/api.rst

@@ -0,0 +1,113 @@
+.. _api_reference_toplevel:
+
+#############
+API Reference
+#############
+
+****************
+Database.Base
+****************
+
+.. automodule:: gitdb.db.base
+   :members:
+   :undoc-members:
+
+****************
+Database.Git
+****************
+
+.. automodule:: gitdb.db.git
+   :members:
+   :undoc-members:
+   
+****************
+Database.Loose
+****************
+
+.. automodule:: gitdb.db.loose
+   :members:
+   :undoc-members:
+   
+****************
+Database.Memory
+****************
+
+.. automodule:: gitdb.db.mem
+   :members:
+   :undoc-members:
+   
+****************
+Database.Pack
+****************
+
+.. automodule:: gitdb.db.pack
+   :members:
+   :undoc-members:
+   
+******************
+Database.Reference
+******************
+
+.. automodule:: gitdb.db.ref
+   :members:
+   :undoc-members:
+   
+************
+Base
+************
+
+.. automodule:: gitdb.base
+   :members:
+   :undoc-members:  
+
+************
+Functions
+************
+
+.. automodule:: gitdb.fun
+   :members:
+   :undoc-members:  
+
+************
+Pack
+************
+
+.. automodule:: gitdb.pack
+   :members:
+   :undoc-members:  
+   
+************
+Streams
+************
+
+.. automodule:: gitdb.stream
+   :members:
+   :undoc-members:  
+
+************
+Types
+************
+
+.. automodule:: gitdb.typ
+   :members:
+   :undoc-members:  
+
+   
+************
+Utilities
+************
+
+.. automodule:: gitdb.util
+   :members:
+   :undoc-members:  
+
+   
+
+   
+
+
+
+   
+
+   
+

doc/source/conf.py

@@ -16,7 +16,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('../../../'))
 
 # -- General configuration -----------------------------------------------------
 

doc/source/index.rst

@@ -10,6 +10,10 @@ Contents:
 
 .. toctree::
    :maxdepth: 2
+   
+   intro
+   tutorial
+   api
 
 Indices and tables
 ==================

doc/source/intro.rst

@@ -0,0 +1,4 @@
+########
+Overview
+########
+

doc/source/tutorial.rst

@@ -0,0 +1,4 @@
+
+########
+Tutorial
+########

fun.py

@@ -39,20 +39,22 @@
 # used when dealing with larger streams
 chunk_size = 1000*mmap.PAGESIZE
 
-__all__ = ('is_loose_object', 'loose_object_header_info', 'object_header_info', 
-			'write_object' )
+__all__ = ('is_loose_object', 'loose_object_header_info', 'msb_size', 'pack_object_header_info', 
+			'write_object', 'loose_object_header', 'stream_copy', 'apply_delta_data' )
 
 #{ Routines
 
 def is_loose_object(m):
-	""":return: True the file contained in memory map m appears to be a loose object.
-	Only the first two bytes are needed"""
+	"""
+	:return: True the file contained in memory map m appears to be a loose object.
+		Only the first two bytes are needed"""
 	b0, b1 = map(ord, m[:2])
 	word = (b0 << 8) + b1
 	return b0 == 0x78 and (word % 31) == 0
 
 def loose_object_header_info(m):
-	""":return: tuple(type_string, uncompressed_size_in_bytes) the type string of the 
+	"""
+	:return: tuple(type_string, uncompressed_size_in_bytes) the type string of the 
 		object as well as its uncompressed size in bytes.
 	:param m: memory map from which to read the compressed object data"""
 	decompress_size = 8192		# is used in cgit as well
@@ -61,9 +63,10 @@ def loose_object_header_info(m):
 	return type_name, int(size)
 
 def pack_object_header_info(data):
-	""":return: tuple(type_id, uncompressed_size_in_bytes, byte_offset)
-	The type_id should be interpreted according to the ``type_id_to_type_map`` map
-	The byte-offset specifies the start of the actual zlib compressed datastream
+	"""
+	:return: tuple(type_id, uncompressed_size_in_bytes, byte_offset)
+		The type_id should be interpreted according to the ``type_id_to_type_map`` map
+		The byte-offset specifies the start of the actual zlib compressed datastream
 	:param m: random-access memory, like a string or memory map"""
 	c = ord(data[0])				# first byte
 	i = 1							# next char to read
@@ -87,8 +90,9 @@ def pack_object_header_info(data):
 	# END handle exceptions
 
 def msb_size(data, offset=0):
-	""":return: tuple(read_bytes, size) read the msb size from the given random 
-	access data starting at the given byte offset"""
+	"""
+	:return: tuple(read_bytes, size) read the msb size from the given random 
+		access data starting at the given byte offset"""
 	size = 0
 	i = 0
 	l = len(data)
@@ -107,12 +111,14 @@ def msb_size(data, offset=0):
 	return i+offset, size 
 
 def loose_object_header(type, size):
-	""":return: string representing the loose object header, which is immediately
+	"""
+	:return: string representing the loose object header, which is immediately
 		followed by the content stream of size 'size'"""
 	return "%s %i\0" % (type, size)
 
 def write_object(type, size, read, write, chunk_size=chunk_size):
-	"""Write the object as identified by type, size and source_stream into the 
+	"""
+	Write the object as identified by type, size and source_stream into the 
 	target_stream
 	
 	:param type: type string of the object
@@ -131,8 +137,10 @@ def write_object(type, size, read, write, chunk_size=chunk_size):
 	return tbw
 
 def stream_copy(read, write, size, chunk_size):
-	"""Copy a stream up to size bytes using the provided read and write methods, 
+	"""
+	Copy a stream up to size bytes using the provided read and write methods, 
 	in chunks of chunk_size
+	
 	:note: its much like stream_copy utility, but operates just using methods"""
 	dbw = 0												# num data bytes written
 
@@ -156,8 +164,10 @@ def stream_copy(read, write, size, chunk_size):
 
 
 def apply_delta_data(src_buf, src_buf_size, delta_buf, delta_buf_size, target_file):
-	"""Apply data from a delta buffer using a source buffer to the target file, 
+	"""
+	Apply data from a delta buffer using a source buffer to the target file, 
 	which will be written to
+	
 	:param src_buf: random access data from which the delta was created
 	:param src_buf_size: size of the source buffer in bytes
 	:param delta_buf_size: size fo the delta buffer in bytes