Fixed up docs for upcoming release. Bumped version to 0.5.3

Author: Byron

Makefile

@@ -23,5 +23,5 @@ clean::
 	rm -f *.so
 
 coverage:: build
-	PYTHONPATH=. $(PYTHON) $(TESTRUNNER) --cover-package=dulwich --with-coverage --cover-erase --cover-inclusive gitdb
+	PYTHONPATH=. $(PYTHON) $(TESTRUNNER) --cover-package=gitdb --with-coverage --cover-erase --cover-inclusive gitdb
 

gitdb/__init__.py

@@ -24,6 +24,13 @@ def _init_externals():
 
 _init_externals()
 
+__author__ = "Sebastian Thiel"
+__contact__ = "byronimo@gmail.com"
+__homepage__ = "https://github.com/gitpython-developers/gitdb"
+version_info = (0, 5, 3)
+__version__ = '.'.join(str(i) for i in version_info)
+
+
 # default imports
 from db import *
 from base import *

gitdb/db/base.py

@@ -72,7 +72,8 @@ def stream_async(self, reader):
 		:param reader: see ``info``
 		:param max_threads: see ``ObjectDBW.store``
 		:return: async.Reader yielding OStream|InvalidOStream instances in any order
-		:note: depending on the system configuration, it might not be possible to 
+		
+		**Note:** depending on the system configuration, it might not be possible to 
 			read all OStreams at once. Instead, read them individually using reader.read(x)
 			where x is small enough."""
 		# base implementation just uses the stream method repeatedly
@@ -140,7 +141,7 @@ def store_async(self, reader):
 			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 
+		**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."""
 		# base implementation uses store to perform the work
@@ -158,7 +159,7 @@ def __init__(self, root_path):
 		"""Initialize this instance to look for its files at the given root path
 		All subsequent operations will be relative to this path
 		:raise InvalidDBRoot: 
-		:note: The base will not perform any accessablity checking as the base
+		**Note:** The base will not perform any accessablity checking as the base
 			might not yet be accessible, but become accessible before the first 
 			access."""
 		super(FileDBBase, self).__init__()

gitdb/db/mem.py

@@ -33,7 +33,7 @@ class MemoryDB(ObjectDBR, ObjectDBW):
 	it to the actual physical storage, as it allows to query whether object already
 	exists in the target storage before introducing actual IO
 	
-	:note: memory is currently not threadsafe, hence the async methods cannot be used
+	**Note:** memory is currently not threadsafe, hence the async methods cannot be used
 		for storing"""
 
 	def __init__(self):
@@ -92,7 +92,7 @@ def sha_iter(self):
 	def stream_copy(self, sha_iter, odb):
 		"""Copy the streams as identified by sha's yielded by sha_iter into the given odb
 		The streams will be copied directly
-		:note: the object will only be written if it did not exist in the target db
+		**Note:** the object will only be written if it did not exist in the target db
 		:return: amount of streams actually copied into odb. If smaller than the amount
 			of input shas, one or more objects did already exist in odb"""
 		count = 0

gitdb/db/pack.py

@@ -58,7 +58,7 @@ def _pack_info(self, sha):
 		""":return: tuple(entity, index) for an item at the given sha
 		:param sha: 20 or 40 byte sha
 		:raise BadObject:
-		:note: This method is not thread-safe, but may be hit in multi-threaded
+		**Note:** This method is not thread-safe, but may be hit in multi-threaded
 			operation. The worst thing that can happen though is a counter that 
 			was not incremented, or the list being in wrong order. So we safe
 			the time for locking here, lets see how that goes"""

gitdb/ext/smmap

@@ -138,7 +138,7 @@ def _closest_index(dcl, absofs):
 	""":return: index at which the given absofs should be inserted. The index points
 	to the DeltaChunk with a target buffer absofs that equals or is greater than
 	absofs. 
-	:note: global method for performance only, it belongs to DeltaChunkList"""
+	**Note:** global method for performance only, it belongs to DeltaChunkList"""
 	lo = 0
 	hi = len(dcl)
 	while lo < hi:
@@ -414,9 +414,11 @@ def pack_object_header_info(data):
 	return (type_id, size, i)
 
 def create_pack_object_header(obj_type, obj_size):
-	""":return: string defining the pack header comprised of the object type
-	and its incompressed size in bytes
-	:parmam obj_type: pack type_id of the object
+	"""
+	:return: string defining the pack header comprised of the object type
+		and its incompressed size in bytes
+	
+	:param obj_type: pack type_id of the object
 	:param obj_size: uncompressed size in bytes of the following object stream"""
 	c = 0		# 1 byte
 	hdr = str()	# output string
@@ -483,7 +485,7 @@ def stream_copy(read, write, size, chunk_size):
 	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"""
+	**Note:** its much like stream_copy utility, but operates just using methods"""
 	dbw = 0												# num data bytes written
 
 	# WRITE ALL DATA UP TO SIZE
@@ -597,7 +599,8 @@ def apply_delta_data(src_buf, src_buf_size, delta_buf, delta_buf_size, write):
 	:param delta_buf_size: size fo the delta buffer in bytes
 	:param delta_buf: random access delta data
 	:param write: write method taking a chunk of bytes
-	:note: transcribed to python from the similar routine in patch-delta.c"""
+	
+	**Note:** transcribed to python from the similar routine in patch-delta.c"""
 	i = 0
 	db = delta_buf
 	while i < delta_buf_size:

gitdb/fun.py

@@ -173,7 +173,7 @@ def write_stream_to_pack(read, write, zstream, base_crc=None):
 class IndexWriter(object):
 	"""Utility to cache index information, allowing to write all information later
 	in one go to the given stream
-	:note: currently only writes v2 indices"""
+	**Note:** currently only writes v2 indices"""
 	__slots__ = '_objs'
 
 	def __init__(self):
@@ -391,7 +391,8 @@ def indexfile_checksum(self):
 
 	def offsets(self):
 		""":return: sequence of all offsets in the order in which they were written
-		:note: return value can be random accessed, but may be immmutable"""
+		
+		**Note:** return value can be random accessed, but may be immmutable"""
 		if self._version == 2:
 			# read stream to array, convert to tuple
 			a = array.array('I')	# 4 byte unsigned int, long are 8 byte on 64 bit it appears
@@ -497,10 +498,10 @@ class PackFile(LazyMixin):
 	packs therefor is 32 bit on 32 bit systems. On 64 bit systems, this should be 
 	fine though.
 	
-	:note: at some point, this might be implemented using streams as well, or 
-		streams are an alternate path in the case memory maps cannot be created
-		for some reason - one clearly doesn't want to read 10GB at once in that 
-		case"""
+	**Note:** at some point, this might be implemented using streams as well, or 
+	streams are an alternate path in the case memory maps cannot be created
+	for some reason - one clearly doesn't want to read 10GB at once in that 
+	case"""
 
 	__slots__ = ('_packpath', '_cursor', '_size', '_version')
 	pack_signature = 0x5041434b		# 'PACK'
@@ -625,8 +626,9 @@ def stream_iter(self, start_offset=0):
 			to access the data in the pack directly.
 		:param start_offset: offset to the first object to iterate. If 0, iteration 
 			starts at the very first object in the pack.
-		:note: Iterating a pack directly is costly as the datastream has to be decompressed
-			to determine the bounds between the objects"""
+			
+		**Note:** Iterating a pack directly is costly as the datastream has to be decompressed
+		to determine the bounds between the objects"""
 		return self._iter_objects(start_offset, as_stream=True)
 
 	#} END Read-Database like Interface
@@ -902,9 +904,11 @@ def write_pack(cls, object_iter, pack_write, index_write=None,
 		:param zlib_compression: the zlib compression level to use
 		:return: tuple(pack_sha, index_binsha) binary sha over all the contents of the pack
 			and over all contents of the index. If index_write was None, index_binsha will be None
-		:note: The destination of the write functions is up to the user. It could
-			be a socket, or a file for instance
-		:note: writes only undeltified objects"""
+			
+		**Note:** The destination of the write functions is up to the user. It could
+		be a socket, or a file for instance
+		
+		**Note:** writes only undeltified objects"""
 		objs = object_iter
 		if not object_count:
 			if not isinstance(object_iter, (tuple, list)):
@@ -979,7 +983,8 @@ def create(cls, object_iter, base_dir, object_count = None, zlib_compression = z
 		and corresponding index file. The pack contains all OStream objects contained in object iter.
 		:param base_dir: directory which is to contain the files
 		:return: PackEntity instance initialized with the new pack
-		:note: for more information on the other parameters see the write_pack method"""
+		
+		**Note:** for more information on the other parameters see the write_pack method"""
 		pack_fd, pack_path = tempfile.mkstemp('', 'pack', base_dir)
 		index_fd, index_path = tempfile.mkstemp('', 'index', base_dir)
 		pack_write = lambda d: os.write(pack_fd, d)

gitdb/pack.py

@@ -51,7 +51,7 @@ class DecompressMemMapReader(LazyMixin):
 	To read efficiently, you clearly don't want to read individual bytes, instead, 
 	read a few kilobytes at least.
 	
-	:note: The chunk-size should be carefully selected as it will involve quite a bit 
+	**Note:** The chunk-size should be carefully selected as it will involve quite a bit 
 		of string copying due to the way the zlib is implemented. Its very wasteful, 
 		hence we try to find a good tradeoff between allocation time and number of 
 		times we actually allocate. An own zlib implementation would be good here
@@ -609,8 +609,8 @@ class FDCompressedSha1Writer(Sha1Writer):
 	"""Digests data written to it, making the sha available, then compress the 
 	data and write it to the file descriptor
 	
-	:note: operates on raw file descriptors
-	:note: for this to work, you have to use the close-method of this instance"""
+	**Note:** operates on raw file descriptors
+	**Note:** for this to work, you have to use the close-method of this instance"""
 	__slots__ = ("fd", "sha1", "zip")
 
 	# default exception

gitdb/stream.py

@@ -65,7 +65,7 @@ def _assert_object_writing_simple(self, db):
 
 	def _assert_object_writing(self, db):
 		"""General tests to verify object writing, compatible to ObjectDBW
-		:note: requires write access to the database"""
+		**Note:** requires write access to the database"""
 		# start in 'dry-run' mode, using a simple sha1 writer
 		ostreams = (ZippedStoreShaWriter, None)
 		for ostreamcls in ostreams: