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

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)

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")

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"] = {}

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)

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")

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:

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)
 

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")

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:

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()