From 662bfb94db5a0189f8cb4973dc811999fbc630bb Mon Sep 17 00:00:00 2001
From: Stephan Creutz <stephan.cr@gmx.de>
Date: Thu, 29 Dec 2022 14:50:43 +0100
Subject: [PATCH] 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.
---
git/cmd.py | 6 ++++--
git/index/base.py | 4 ++--
git/index/fun.py | 11 +++++++----
git/objects/base.py | 1 +
git/objects/fun.py | 2 ++
git/objects/tree.py | 4 +++-
git/objects/util.py | 1 +
git/refs/log.py | 2 ++
git/refs/reference.py | 3 ++-
git/remote.py | 11 +++++++----
git/repo/base.py | 3 +++
git/util.py | 6 +++---
12 files changed, 37 insertions(+), 17 deletions(-)
diff --git a/git/cmd.py b/git/cmd.py
index 3dd5aad33..f2a9e16d2 100644
--- a/git/cmd.py
+++ b/git/cmd.py
@@ -690,6 +690,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)
@@ -870,7 +871,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
@@ -1339,7 +1340,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 --git a/git/index/base.py b/git/index/base.py
index 17d18db58..cda08de25 100644
--- a/git/index/base.py
+++ b/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 --git a/git/index/fun.py b/git/index/fun.py
index 4659ac898..d0925ed51 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 9d0057254..eb9a8ac3d 100644
--- a/git/objects/base.py
+++ b/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 --git a/git/objects/fun.py b/git/objects/fun.py
index 001e10e47..e91403a8b 100644
--- a/git/objects/fun.py
+++ b/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 --git a/git/objects/tree.py b/git/objects/tree.py
index b72e88c48..a9b491e23 100644
--- a/git/objects/tree.py
+++ b/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 --git a/git/objects/util.py b/git/objects/util.py
index 636a58316..f405d6287 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 a5f4de58b..1f86356a4 100644
--- a/git/refs/log.py
+++ b/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 --git a/git/refs/reference.py b/git/refs/reference.py
index ca43cc430..4f9e3a0a7 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 @@ 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 --git a/git/remote.py b/git/remote.py
index 483d536ae..b618391dd 100644
--- a/git/remote.py
+++ b/git/remote.py
@@ -731,6 +731,7 @@ def stale_refs(self) -> IterableList[Reference]:
@classmethod
def create(cls, repo: "Repo", name: str, url: str, **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
@@ -750,6 +751,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)
@@ -762,6 +764,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
@@ -981,11 +984,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 --git a/git/repo/base.py b/git/repo/base.py
index 49a3d5a16..97ea81e93 100644
--- a/git/repo/base.py
+++ b/git/repo/base.py
@@ -387,6 +387,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)
@@ -427,6 +428,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)
@@ -441,6 +443,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 --git a/git/util.py b/git/util.py
index 6a4a65579..30028b1c2 100644
--- a/git/util.py
+++ b/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