Fixed API reference docs as far as possible

Author: Byron

doc/source/reference.rst

@@ -45,10 +45,24 @@ Objects.Functions
    :members:
    :undoc-members:
 
-Objects.Submodule
------------------
+Objects.Submodule.base
+----------------------
+
+.. automodule:: git.objects.submodule.base
+   :members:
+   :undoc-members:
+
+Objects.Submodule.root
+----------------------
 
-.. automodule:: git.objects.submodule
+.. automodule:: git.objects.submodule.root
+   :members:
+   :undoc-members:
+   
+Objects.Submodule.util
+----------------------
+
+.. automodule:: git.objects.submodule.util
    :members:
    :undoc-members:
 
@@ -109,10 +123,10 @@ Diff
    :members:
    :undoc-members:
 
-Errors
-------
+Exceptions
+----------
 
-.. automodule:: git.errors
+.. automodule:: git.exc
    :members:
    :undoc-members:
 

lib/git/objects/submodule/base.py

@@ -722,9 +722,10 @@ def module_exists(self):
 		# END handle exception
 
 	def exists(self):
-		""":return: True if the submodule exists, False otherwise. Please note that
-		a submodule may exist (in the .gitmodules file) even though its module
-		doesn't exist"""
+		"""
+		:return: True if the submodule exists, False otherwise. Please note that
+			a submodule may exist (in the .gitmodules file) even though its module
+			doesn't exist"""
 		# keep attributes for later, and restore them if we have no valid data
 		# this way we do not actually alter the state of the object
 		loc = locals()
@@ -758,7 +759,8 @@ def branch(self):
 
 	@property
 	def branch_path(self):
-		""":return: full (relative) path as string to the branch we would checkout
+		"""
+		:return: full (relative) path as string to the branch we would checkout
 			from the remote and track"""
 		return self._branch_path
 
@@ -792,17 +794,19 @@ def name(self):
 		return self._name
 
 	def config_reader(self):
-		""":return: ConfigReader instance which allows you to qurey the configuration values
-		of this submodule, as provided by the .gitmodules file
+		"""
+		:return: ConfigReader instance which allows you to qurey the configuration values
+			of this submodule, as provided by the .gitmodules file
 		:note: The config reader will actually read the data directly from the repository
 			and thus does not need nor care about your working tree.
 		:note: Should be cached by the caller and only kept as long as needed
 		:raise IOError: If the .gitmodules file/blob could not be read"""
 		return self._config_parser_constrained(read_only=True)
 
 	def children(self):
-		""":return: IterableList(Submodule, ...) an iterable list of submodules instances
-		which are children of this submodule
+		"""
+		:return: IterableList(Submodule, ...) an iterable list of submodules instances
+			which are children of this submodule
 		:raise InvalidGitRepositoryError: if the submodule is not checked-out"""
 		return self._get_intermediate_items(self)
 

lib/git/objects/util.py

@@ -276,7 +276,8 @@ def _get_intermediate_items(cls, item):
 		raise NotImplementedError("To be implemented in subclass")
 
 	def list_traverse(self, *args, **kwargs):
-		""":return: IterableList with the results of the traversal as produced by
+		"""
+		:return: IterableList with the results of the traversal as produced by
 			traverse()"""
 		out = IterableList(self._id_attribute_)
 		out.extend(self.traverse(*args, **kwargs))

lib/git/refs.py

@@ -644,8 +644,9 @@ def __init__(self, repo, path=_HEAD_NAME):
 		super(HEAD, self).__init__(repo, path)
 
 	def orig_head(self):
-		""":return: SymbolicReference pointing at the ORIG_HEAD, which is maintained 
-		to contain the previous value of HEAD"""
+		"""
+		:return: SymbolicReference pointing at the ORIG_HEAD, which is maintained 
+			to contain the previous value of HEAD"""
 		return SymbolicReference(self.repo, self._ORIG_HEAD_NAME)
 
 	def _set_reference(self, ref):
@@ -795,8 +796,10 @@ def delete(cls, repo, *heads, **kwargs):
 
 
 	def set_tracking_branch(self, remote_reference):
-		"""Configure this branch to track the given remote reference. This will alter
-		this branch's configuration accordingly.
+		"""
+		Configure this branch to track the given remote reference. This will alter
+			this branch's configuration accordingly.
+		
 		:param remote_reference: The remote reference to track or None to untrack 
 			any references
 		:return: self"""
@@ -820,7 +823,8 @@ def set_tracking_branch(self, remote_reference):
 
 
 	def tracking_branch(self):
-		""":return: The remote_reference we are tracking, or None if we are 
+		"""
+		:return: The remote_reference we are tracking, or None if we are 
 			not a tracking branch"""
 		reader = self.config_reader()
 		if reader.has_option(self.k_config_remote) and reader.has_option(self.k_config_remote_ref):
@@ -896,12 +900,14 @@ def _config_parser(self, read_only):
 		return SectionConstraint(parser, 'branch "%s"' % self.name)
 
 	def config_reader(self):
-		""":return: A configuration parser instance constrained to only read 
-		this instance's values"""
+		"""
+		:return: A configuration parser instance constrained to only read 
+			this instance's values"""
 		return self._config_parser(read_only=True)
 
 	def config_writer(self):
-		""":return: A configuration writer instance with read-and write acccess
+		"""
+		:return: A configuration writer instance with read-and write acccess
 			to options of this head"""
 		return self._config_parser(read_only=False)
 

lib/git/repo/base.py

@@ -226,12 +226,13 @@ def remote(self, name='origin'):
 
 	@property
 	def submodules(self):
-		""":return: git.IterableList(Submodule, ...) of direct submodules
+		"""
+		:return: git.IterableList(Submodule, ...) of direct submodules
 			available from the current head"""
 		return Submodule.list_items(self)
 
 	def submodule(self, name):
-		""":return: Submodule with the given name
+		""" :return: Submodule with the given name 
 		:raise ValueError: If no such submodule exists"""
 		try:
 			return self.submodules[name]
@@ -241,6 +242,7 @@ def submodule(self, name):
 
 	def create_submodule(self, *args, **kwargs):
 		"""Create a new submodule
+		
 		:note: See the documentation of Submodule.add for a description of the 
 			applicable parameters
 		:return: created submodules"""
@@ -719,7 +721,7 @@ def clone_from(cls, url, to_path, **kwargs):
 		"""Create a clone from the given URL
 		:param url: valid git url, see http://www.kernel.org/pub/software/scm/git/docs/git-clone.html#URLS
 		:param to_path: Path to which the repository should be cloned to
-		:param **kwargs: see the ``clone`` method
+		:param kwargs: see the ``clone`` method
 		:return: Repo instance pointing to the cloned directory"""
 		return cls._clone(Git(os.getcwd()), url, to_path, GitCmdObjectDB, **kwargs)