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.

Author: stephan-cr

Diff for: git/cmd.py

@@ -735,6 +735,7 @@ def __init__(self, working_dir: Union[None, PathLike] = None):
     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 @@ def execute(
             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 @@ def get_object_header(self, ref: str) -> Tuple[str, str, int]:
 
     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 for: git/index/base.py

@@ -982,12 +982,12 @@ def move(
             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 for: 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 for: git/objects/base.py

@@ -143,6 +143,7 @@ def data_stream(self) -> "OStream":
 
     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 for: git/objects/fun.py

@@ -37,6 +37,7 @@
 
 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 for: git/objects/tree.py

@@ -128,6 +128,7 @@ def set_done(self) -> "TreeModifier":
         """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 @@ def add_unchecked(self, binsha: bytes, mode: int, name: str) -> None:
         """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 @@ def _iter_convert_to_object(self, iterable: Iterable[TreeCacheTup]) -> Iterator[
 
     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 for: 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 for: git/refs/log.py

@@ -253,6 +253,7 @@ def entry_at(cls, filepath: PathLike, index: int) -> "RefLogEntry":
 
     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 @@ def append_entry(
 
     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 for: 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 @@ def set_object(
         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 for: git/remote.py

@@ -756,6 +756,7 @@ def stale_refs(self) -> IterableList[Reference]:
     @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 @@ def add(cls, repo: "Repo", name: str, url: str, **kwargs: Any) -> "Remote":
     @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 @@ def remove(cls, repo: "Repo", name: str) -> str:
 
     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 @@ def pull(
         """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 for: git/repo/base.py

@@ -403,6 +403,7 @@ def head(self) -> "HEAD":
     @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 @@ def create_submodule(self, *args: Any, **kwargs: Any) -> Submodule:
     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 @@ def submodule_update(self, *args: Any, **kwargs: Any) -> Iterator[Submodule]:
     @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 for: git/util.py

@@ -131,7 +131,7 @@
 
 
 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 @@ def list_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Any:
 
         :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 @@ def list_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> IterableList[T_I
 
         :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