Fix Sphinx rendering errors

These errors are mostly fixed by either adding blank lines or single
spaces for Sphinx documentation key words.

The commit solely includes documentation changes, no functional
changes.

12 files changed, 37 insertions, 17 deletions

diff --git a/git/cmd.py b/git/cmd.py
index 9ef1e3a6..134001e2 100644
--- a/git/cmd.py
+++ b/git/cmd.py
@@ -735,6 +735,7 @@ class Git(LazyMixin):
     def __getattr__(self, name: str) -> Any:
         """A convenience method as it allows to call the command as if it was
         an object.
+
         :return: Callable object that will execute call _call_process with your arguments."""
         if name[0] == "_":
             return LazyMixin.__getattr__(self, name)
@@ -915,7 +916,7 @@ class Git(LazyMixin):
             render the repository incapable of accepting changes until the lock is manually
             removed.
         :param strip_newline_in_stdout:
-            Whether to strip the trailing `\n` of the command stdout.
+            Whether to strip the trailing ``\\n`` of the command stdout.
         :return:
             * str(output) if extended_output = False (Default)
             * tuple(int(status), str(stdout), str(stderr)) if extended_output = True
@@ -1384,7 +1385,8 @@ class Git(LazyMixin):
 
     def get_object_data(self, ref: str) -> Tuple[str, str, int, bytes]:
         """As get_object_header, but returns object data as well
-        :return: (hexsha, type_string, size_as_int,data_string)
+
+        :return: (hexsha, type_string, size_as_int, data_string)
         :note: not threadsafe"""
         hexsha, typename, size, stream = self.stream_object_data(ref)
         data = stream.read(size)
diff --git a/git/index/base.py b/git/index/base.py
index 17d18db5..cda08de2 100644
--- a/git/index/base.py
+++ b/git/index/base.py
@@ -982,12 +982,12 @@ class IndexFile(LazyMixin, git_diff.Diffable, Serializable):
             Additional arguments you would like to pass to git-mv, such as dry_run
             or force.
 
-        :return:List(tuple(source_path_string, destination_path_string), ...)
+        :return: List(tuple(source_path_string, destination_path_string), ...)
             A list of pairs, containing the source file moved as well as its
             actual destination. Relative to the repository root.
 
         :raise ValueError: If only one item was given
-            GitCommandError: If git could not handle your request"""
+        :raise GitCommandError: If git could not handle your request"""
         args = []
         if skip_errors:
             args.append("-k")
diff --git a/git/index/fun.py b/git/index/fun.py
index 4659ac89..d0925ed5 100644
--- a/git/index/fun.py
+++ b/git/index/fun.py
@@ -82,6 +82,7 @@ def _has_file_extension(path):
 
 def run_commit_hook(name: str, index: "IndexFile", *args: str) -> None:
     """Run the commit hook of the given name. Silently ignores hooks that do not exist.
+
     :param name: name of hook, like 'pre-commit'
     :param index: IndexFile instance
     :param args: arguments passed to hook file
@@ -234,11 +235,13 @@ def read_cache(
     stream: IO[bytes],
 ) -> Tuple[int, Dict[Tuple[PathLike, int], "IndexEntry"], bytes, bytes]:
     """Read a cache file from the given stream
+
     :return: tuple(version, entries_dict, extension_data, content_sha)
-    * version is the integer version number
-    * entries dict is a dictionary which maps IndexEntry instances to a path at a stage
-    * extension_data is '' or 4 bytes of type + 4 bytes of size + size bytes
-    * content_sha is a 20 byte sha on all cache file contents"""
+
+      * version is the integer version number
+      * entries dict is a dictionary which maps IndexEntry instances to a path at a stage
+      * extension_data is '' or 4 bytes of type + 4 bytes of size + size bytes
+      * content_sha is a 20 byte sha on all cache file contents"""
     version, num_entries = read_header(stream)
     count = 0
     entries: Dict[Tuple[PathLike, int], "IndexEntry"] = {}
diff --git a/git/objects/base.py b/git/objects/base.py
index 9d005725..eb9a8ac3 100644
--- a/git/objects/base.py
+++ b/git/objects/base.py
@@ -143,6 +143,7 @@ class Object(LazyMixin):
 
     def stream_data(self, ostream: "OStream") -> "Object":
         """Writes our data directly to the given output stream
+
         :param ostream: File object compatible stream object.
         :return: self"""
         istream = self.repo.odb.stream(self.binsha)
diff --git a/git/objects/fun.py b/git/objects/fun.py
index 001e10e4..e91403a8 100644
--- a/git/objects/fun.py
+++ b/git/objects/fun.py
@@ -37,6 +37,7 @@ __all__ = (
 
 def tree_to_stream(entries: Sequence[EntryTup], write: Callable[["ReadableBuffer"], Union[int, None]]) -> None:
     """Write the give list of entries into a stream using its write method
+
     :param entries: **sorted** list of tuples with (binsha, mode, name)
     :param write: write method which takes a data string"""
     ord_zero = ord("0")
@@ -68,6 +69,7 @@ def tree_to_stream(entries: Sequence[EntryTup], write: Callable[["ReadableBuffer
 
 def tree_entries_from_data(data: bytes) -> List[EntryTup]:
     """Reads the binary representation of a tree and returns tuples of Tree items
+
     :param data: data block with tree data (as bytes)
     :return: list(tuple(binsha, mode, tree_relative_path), ...)"""
     ord_zero = ord("0")
diff --git a/git/objects/tree.py b/git/objects/tree.py
index b72e88c4..a9b491e2 100644
--- a/git/objects/tree.py
+++ b/git/objects/tree.py
@@ -128,6 +128,7 @@ class TreeModifier(object):
         """Call this method once you are done modifying the tree information.
         It may be called several times, but be aware that each call will cause
         a sort operation
+
         :return self:"""
         merge_sort(self._cache, git_cmp)
         return self
@@ -175,6 +176,7 @@ class TreeModifier(object):
         """Add the given item to the tree, its correctness is assumed, which
         puts the caller into responsibility to assure the input is correct.
         For more information on the parameters, see ``add``
+
         :param binsha: 20 byte binary sha"""
         assert isinstance(binsha, bytes) and isinstance(mode, int) and isinstance(name, str)
         tree_cache = (binsha, mode, name)
@@ -259,8 +261,8 @@ class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
 
     def join(self, file: str) -> IndexObjUnion:
         """Find the named object in this tree's contents
-        :return: ``git.Blob`` or ``git.Tree`` or ``git.Submodule``
 
+        :return: ``git.Blob`` or ``git.Tree`` or ``git.Submodule``
         :raise KeyError: if given file or tree does not exist in tree"""
         msg = "Blob or Tree named %r not found"
         if "/" in file:
diff --git a/git/objects/util.py b/git/objects/util.py
index 636a5831..f405d628 100644
--- a/git/objects/util.py
+++ b/git/objects/util.py
@@ -140,6 +140,7 @@ def utctz_to_altz(utctz: str) -> int:
     """we convert utctz to the timezone in seconds, it is the format time.altzone
     returns. Git stores it as UTC timezone which has the opposite sign as well,
     which explains the -1 * ( that was made explicit here )
+
     :param utctz: git utc timezone string, i.e. +0200"""
     return -1 * int(float(utctz) / 100 * 3600)
 
diff --git a/git/refs/log.py b/git/refs/log.py
index a5f4de58..1f86356a 100644
--- a/git/refs/log.py
+++ b/git/refs/log.py
@@ -253,6 +253,7 @@ class RefLog(List[RefLogEntry], Serializable):
 
     def to_file(self, filepath: PathLike) -> None:
         """Write the contents of the reflog instance to a file at the given filepath.
+
         :param filepath: path to file, parent directories are assumed to exist"""
         lfd = LockedFD(filepath)
         assure_directory_exists(filepath, is_file=True)
@@ -326,6 +327,7 @@ class RefLog(List[RefLogEntry], Serializable):
 
     def write(self) -> "RefLog":
         """Write this instance's data to the file we are originating from
+
         :return: self"""
         if self._path is None:
             raise ValueError("Instance was not initialized with a path, use to_file(...) instead")
diff --git a/git/refs/reference.py b/git/refs/reference.py
index ca43cc43..4f9e3a0a 100644
--- a/git/refs/reference.py
+++ b/git/refs/reference.py
@@ -49,8 +49,8 @@ class Reference(SymbolicReference, LazyMixin, IterableObj):
 
     def __init__(self, repo: "Repo", path: PathLike, check_path: bool = True) -> None:
         """Initialize this instance
-        :param repo: Our parent repository
 
+        :param repo: Our parent repository
         :param path:
             Path relative to the .git/ directory pointing to the ref in question, i.e.
             refs/heads/master
@@ -73,6 +73,7 @@ class Reference(SymbolicReference, LazyMixin, IterableObj):
         logmsg: Union[str, None] = None,
     ) -> "Reference":
         """Special version which checks if the head-log needs an update as well
+
         :return: self"""
         oldbinsha = None
         if logmsg is not None:
diff --git a/git/remote.py b/git/remote.py
index 4240223e..3f86a297 100644
--- a/git/remote.py
+++ b/git/remote.py
@@ -756,6 +756,7 @@ class Remote(LazyMixin, IterableObj):
     @classmethod
     def create(cls, repo: "Repo", name: str, url: str, allow_unsafe_protocols: bool = False, **kwargs: Any) -> "Remote":
         """Create a new remote to the given repository
+
         :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
@@ -778,6 +779,7 @@ class Remote(LazyMixin, IterableObj):
     @classmethod
     def remove(cls, repo: "Repo", name: str) -> str:
         """Remove the remote with the given name
+
         :return: the passed remote name to remove
         """
         repo.git.remote("rm", name)
@@ -790,6 +792,7 @@ class Remote(LazyMixin, IterableObj):
 
     def rename(self, new_name: str) -> "Remote":
         """Rename self to the given new_name
+
         :return: self"""
         if self.name == new_name:
             return self
@@ -1021,11 +1024,11 @@ class Remote(LazyMixin, IterableObj):
         """Pull changes from the given branch, being the same as a fetch followed
         by a merge of branch with your local branch.
 
-        :param refspec: see 'fetch' method
-        :param progress: see 'push' method
-        :param kill_after_timeout: see 'fetch' method
+        :param refspec: see :meth:`fetch` method
+        :param progress: see :meth:`push` method
+        :param kill_after_timeout: see :meth:`fetch` method
         :param kwargs: Additional arguments to be passed to git-pull
-        :return: Please see 'fetch' method"""
+        :return: Please see :meth:`fetch` method"""
         if refspec is None:
             # No argument refspec, then ensure the repo's config has a fetch refspec.
             self._assert_refspec()
diff --git a/git/repo/base.py b/git/repo/base.py
index d4463f1e..93ed0c71 100644
--- a/git/repo/base.py
+++ b/git/repo/base.py
@@ -403,6 +403,7 @@ class Repo(object):
     @property
     def remotes(self) -> "IterableList[Remote]":
         """A list of Remote objects allowing to access and manipulate remotes
+
         :return: ``git.IterableList(Remote, ...)``"""
         return Remote.list_items(self)
 
@@ -443,6 +444,7 @@ class Repo(object):
     def iter_submodules(self, *args: Any, **kwargs: Any) -> Iterator[Submodule]:
         """An iterator yielding Submodule instances, see Traversable interface
         for a description of args and kwargs
+
         :return: Iterator"""
         return RootModule(self).traverse(*args, **kwargs)
 
@@ -457,6 +459,7 @@ class Repo(object):
     @property
     def tags(self) -> "IterableList[TagReference]":
         """A list of ``Tag`` objects that are available in this repo
+
         :return: ``git.IterableList(TagReference, ...)``"""
         return TagReference.list_items(self)
 
diff --git a/git/util.py b/git/util.py
index 6a4a6557..30028b1c 100644
--- a/git/util.py
+++ b/git/util.py
@@ -131,7 +131,7 @@ T = TypeVar("T")
 
 
 def unbare_repo(func: Callable[..., T]) -> Callable[..., T]:
-    """Methods with this decorator raise InvalidGitRepositoryError if they
+    """Methods with this decorator raise :class:`.exc.InvalidGitRepositoryError` if they
     encounter a bare repository"""
 
     from .exc import InvalidGitRepositoryError
@@ -1152,7 +1152,7 @@ class Iterable(metaclass=IterableClassWatcher):
 
         :note: Favor the iter_items method as it will
 
-        :return:list(Item,...) list of item instances"""
+        :return: list(Item,...) list of item instances"""
         out_list: Any = IterableList(cls._id_attribute_)
         out_list.extend(cls.iter_items(repo, *args, **kwargs))
         return out_list
@@ -1184,7 +1184,7 @@ class IterableObj(Protocol):
 
         :note: Favor the iter_items method as it will
 
-        :return:list(Item,...) list of item instances"""
+        :return: list(Item,...) list of item instances"""
         out_list: IterableList = IterableList(cls._id_attribute_)
         out_list.extend(cls.iter_items(repo, *args, **kwargs))
         return out_list