Shorten some docstring references with tilde notation

This uses the Sphinx ~ notation to express references like:

    :class:`Z <a.b.c.Z>`

In the abbreviated form, which Sphinx renders the same way:

    :class:`~a.b.c.Z`

(This commit also makes some other polishing changes to affected
and nearby text.)

Author: EliahKagan

git/diff.py

@@ -118,12 +118,12 @@ def diff(
             This the item to compare us with.
 
             * If None, we will be compared to the working tree.
-            * If :class:`Treeish <git.index.base.Treeish>`, it will be compared against
-              the respective tree.
-            * If :class:`Index <Diffable.Index>`, it will be compared against the index.
+            * If :class:`~git.index.base.Treeish`, it will be compared against the
+              respective tree.
+            * If :class:`~Diffable.Index`, it will be compared against the index.
             * If :attr:`git.NULL_TREE`, it will compare against the empty tree.
-            * It defaults to :class:`Index <Diffable.Index>` so that the method will not
-              by default fail on bare repositories.
+            * It defaults to :class:`~Diffable.Index` so that the method will not by
+              default fail on bare repositories.
 
         :param paths:
             This a list of paths or a single path to limit the diff to. It will only
@@ -141,11 +141,9 @@ def diff(
         :return: git.DiffIndex
 
         :note:
-            On a bare repository, 'other' needs to be provided
-            as :class:`Index <Diffable.Index>`,
-            or as :class:`Tree <git.objects.tree.Tree>`
-            or :class:`Commit <git.objects.commit.Commit>`, or a git command error will
-            occur.
+            On a bare repository, 'other' needs to be provided as
+            :class:`~Diffable.Index`, or as :class:`~git.objects.tree.Tree` or
+            :class:`~git.objects.commit.Commit`, or a git command error will occur.
         """
         args: List[Union[PathLike, Diffable, Type["Diffable.Index"], object]] = []
         args.append("--abbrev=40")  # We need full shas.
@@ -222,7 +220,7 @@ class DiffIndex(List[T_Diff]):
     def iter_change_type(self, change_type: Lit_change_type) -> Iterator[T_Diff]:
         """
         :return:
-            iterator yielding :class:`Diff` instances that match the given `change_type`
+            Iterator yielding :class:`Diff` instances that match the given `change_type`
 
         :param change_type:
             Member of :attr:`DiffIndex.change_type`, namely:

git/objects/base.py

@@ -178,7 +178,7 @@ def __init__(
     ) -> None:
         """Initialize a newly instanced IndexObject.
 
-        :param repo: The :class:`Repo <git.repo.base.Repo>` we are located in.
+        :param repo: The :class:`~git.repo.base.Repo` we are located in.
         :param binsha: 20 byte sha1.
         :param mode:
             The stat compatible file mode as int, use the :mod:`stat` module to evaluate

git/objects/submodule/base.py

@@ -113,14 +113,16 @@ def __init__(
     ) -> None:
         """Initialize this instance with its attributes.
 
-        We only document the parameters that differ
-        from :class:`IndexObject <git.objects.base.IndexObject>`.
-
-        :param repo: Our parent repository
-        :param binsha: binary sha referring to a commit in the remote repository, see url parameter
-        :param parent_commit: see set_parent_commit()
-        :param url: The url to the remote repository which is the submodule
-        :param branch_path: full (relative) path to ref to checkout when cloning the remote repository
+        We only document the parameters that differ from
+        :class:`~git.objects.base.IndexObject`.
+
+        :param repo: Our parent repository.
+        :param binsha: Binary sha referring to a commit in the remote repository. See
+            the ``url`` parameter.
+        :param parent_commit: See :meth:`set_parent_commit`.
+        :param url: The URL to the remote repository which is the submodule.
+        :param branch_path: Full (relative) path to ref to checkout when cloning the
+            remote repository.
         """
         super(Submodule, self).__init__(repo, binsha, mode, path)
         self.size = 0

git/refs/head.py

@@ -231,8 +231,8 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
 
         :param force:
             If True, changes to the index and the working tree will be discarded.
-            If False, :class:`GitCommandError <git.exc.GitCommandError>` will be
-            raised in that situation.
+            If False, :class:`~git.exc.GitCommandError` will be raised in that
+            situation.
 
         :param kwargs:
             Additional keyword arguments to be passed to git checkout, e.g.

git/refs/reference.py

@@ -40,8 +40,8 @@ def wrapper(self: T_References, *args: Any) -> _T:
 class Reference(SymbolicReference, LazyMixin, IterableObj):
     """A named reference to any object.
 
-    Subclasses may apply restrictions though, e.g., a :class:`Head <git.refs.head.Head>`
-    can only point to commits.
+    Subclasses may apply restrictions though, e.g., a :class:`~git.refs.head.Head` can
+    only point to commits.
     """
 
     __slots__ = ()

git/refs/symbolic.py

@@ -59,7 +59,7 @@ class SymbolicReference:
     """Special case of a reference that is symbolic.
 
     This does not point to a specific commit, but to another
-    :class:`Head <git.refs.head.Head>`, which itself specifies a commit.
+    :class:`~git.refs.head.Head`, which itself specifies a commit.
 
     A typical example for a symbolic reference is ``HEAD``.
     """
@@ -345,7 +345,7 @@ def set_object(
         If the reference does not exist, it will be created.
 
         :param object: A refspec, a :class:`SymbolicReference` or an
-            :class:`Object <git.objects.base.Object>` instance.
+            :class:`~git.objects.base.Object` instance.
             :class:`SymbolicReference` instances will be dereferenced beforehand to
             obtain the object they point to.
         :param logmsg: If not None, the message will be used in the reflog entry to be
@@ -396,10 +396,10 @@ def set_reference(
         symbolic one.
 
         :param ref:
-            A :class:`SymbolicReference` instance,
-            an :class:`Object <git.objects.base.Object>` instance, or a refspec string.
-            Only if the ref is a :class:`SymbolicReference` instance, we will point to
-            it. Everything else is dereferenced to obtain the actual object.
+            A :class:`SymbolicReference` instance, an :class:`~git.objects.base.Object`
+            instance, or a refspec string. Only if the ref is a
+            :class:`SymbolicReference` instance, we will point to it. Everything else is
+            dereferenced to obtain the actual object.
 
         :param logmsg: If set to a string, the message will be used in the reflog.
             Otherwise, a reflog entry is not written for the changed reference.
@@ -514,7 +514,7 @@ def log_append(
         :param message: A message describing the change.
         :param newbinsha: The sha the ref points to now. If None, our current commit sha
             will be used.
-        :return: The added :class:`RefLogEntry <git.refs.log.RefLogEntry>` instance.
+        :return: The added :class:`~git.refs.log.RefLogEntry` instance.
         """
         # NOTE: We use the committer of the currently active commit - this should be
         # correct to allow overriding the committer on a per-commit level.
@@ -540,7 +540,7 @@ def log_entry(self, index: int) -> "RefLogEntry":
 
         .. note:: This method must read part of the reflog during execution, hence
             it should be used sparingly, or only if you need just one index.
-            In that case, it will be faster than the ``log()`` method.
+            In that case, it will be faster than the :meth:`log` method.
         """
         return RefLog.entry_at(RefLog.path(self), index)
 
@@ -816,8 +816,8 @@ def iter_items(
             which is not detached and pointing to a valid ref.
 
             The list is lexicographically sorted. The returned objects are instances of
-            concrete subclasses, such as :class:`Head <git.refs.head.Head>` or
-            :class:`TagReference <git.refs.tag.TagReference>`.
+            concrete subclasses, such as :class:`~git.refs.head.Head` or
+            :class:`~git.refs.tag.TagReference`.
         """
         return (r for r in cls._iter_items(repo, common_path) if r.__class__ is SymbolicReference or not r.is_detached)
 
@@ -826,14 +826,16 @@ def from_path(cls: Type[T_References], repo: "Repo", path: PathLike) -> T_Refere
         """
         Make a symbolic reference from a path.
 
-        :param path: Full ``.git``-directory-relative path name to the Reference to instantiate.
+        :param path: Full ``.git``-directory-relative path name to the Reference to
+            instantiate.
 
-        :note: Use :meth:`to_full_path` if you only have a partial path of a known Reference type.
+        :note: Use :meth:`to_full_path` if you only have a partial path of a known
+            Reference type.
 
         :return:
-            Instance of type :class:`Reference <git.refs.reference.Reference>`,
-            :class:`Head <git.refs.head.Head>`, or :class:`Tag <git.refs.tag.Tag>`,
-            depending on the given path.
+            Instance of type :class:`~git.refs.reference.Reference`,
+            :class:`~git.refs.head.Head`, or :class:`~git.refs.tag.Tag`, depending on
+            the given path.
         """
         if not path:
             raise ValueError("Cannot create Reference from %r" % path)

git/refs/tag.py

@@ -89,8 +89,8 @@ def create(
             The prefix ``refs/tags`` is implied.
 
         :param ref:
-            A reference to the :class:`Object <git.objects.base.Object>` you want to
-            tag. The Object can be a commit, tree or blob.
+            A reference to the :class:`~git.objects.base.Object` you want to tag.
+            The Object can be a commit, tree or blob.
 
         :param logmsg:
             If not None, the message will be used in your tag object. This will also

git/remote.py

@@ -210,9 +210,9 @@ def old_commit(self) -> Union[str, SymbolicReference, Commit_ish, None]:
     def remote_ref(self) -> Union[RemoteReference, TagReference]:
         """
         :return:
-            Remote :class:`Reference <git.refs.reference.Reference>` or
-            :class:`TagReference <git.refs.tag.TagReference>` in the local repository
-            corresponding to the :attr:`remote_ref_string` kept in this instance.
+            Remote :class:`~git.refs.reference.Reference` or
+            :class:`~git.refs.tag.TagReference` in the local repository corresponding to
+            the :attr:`remote_ref_string` kept in this instance.
         """
         # Translate heads to a local remote. Tags stay as they are.
         if self.remote_ref_string.startswith("refs/tags"):
@@ -1093,7 +1093,7 @@ def push(
               `Click here <http://goo.gl/NPa7st>`__ for a description of all arguments
               given to the function.
             * An instance of a class derived from :class:`git.RemoteProgress` that
-              overrides the :meth:`update <git.RemoteProgress.update>` method.
+              overrides the :meth:`~git.RemoteProgress.update` method.
 
         :note: No further progress information is returned after push returns.
 
@@ -1109,14 +1109,14 @@ def push(
         :param kwargs: Additional arguments to be passed to git-push.
 
         :return:
-            A :class:`PushInfoList` object, where each list member
-            represents an individual head which had been updated on the remote side.
+            A :class:`PushInfoList` object, where each list member represents an
+            individual head which had been updated on the remote side.
             If the push contains rejected heads, these will have the
             :attr:`PushInfo.ERROR` bit set in their flags.
-            If the operation fails completely, the length of the returned PushInfoList will
-            be 0.
-            Call :meth:`raise_if_error <PushInfoList.raise_if_error>` on the returned
-            object to raise on any failure.
+            If the operation fails completely, the length of the returned PushInfoList
+            will be 0.
+            Call :meth:`~PushInfoList.raise_if_error` on the returned object to raise on
+            any failure.
         """
         kwargs = add_progress(kwargs, self.repo.git, progress)
 

git/repo/base.py

@@ -387,7 +387,7 @@ def heads(self) -> "IterableList[Head]":
     def references(self) -> "IterableList[Reference]":
         """A list of Reference objects representing tags, heads and remote references.
 
-        :return: IterableList(Reference, ...)
+        :return: ``git.IterableList(Reference, ...)``
         """
         return Reference.list_items(self)
 
@@ -400,11 +400,11 @@ def references(self) -> "IterableList[Reference]":
     @property
     def index(self) -> "IndexFile":
         """
-        :return: :class:`IndexFile <git.index.base.IndexFile>` representing this
-            repository's index.
+        :return: A :class:`~git.index.base.IndexFile` representing this repository's
+            index.
 
         :note: This property can be expensive, as the returned
-            :class:`IndexFile <git.index.base.IndexFile>` will be reinitialized.
+            :class:`~git.index.base.IndexFile` will be reinitialized.
             It is recommended to reuse the object.
         """
         return IndexFile(self)
@@ -520,7 +520,7 @@ def create_head(
         :note: For more documentation, please see the
             :meth:`Head.create <git.refs.head.Head.create>` method.
 
-        :return: Newly created :class:`Head <git.refs.head.Head>` Reference
+        :return: Newly created :class:`~git.refs.head.Head` Reference
         """
         return Head.create(self, path, commit, logmsg, force)
 
@@ -544,7 +544,7 @@ def create_tag(
         :note: For more documentation, please see the
             :meth:`TagReference.create <git.refs.tag.TagReference.create>` method.
 
-        :return: :class:`TagReference <git.refs.tag.TagReference>` object
+        :return: :class:`~git.refs.tag.TagReference` object
         """
         return TagReference.create(self, path, ref, message, force, **kwargs)
 
@@ -558,7 +558,7 @@ def create_remote(self, name: str, url: str, **kwargs: Any) -> Remote:
         For more information, please see the documentation of the
         :meth:`Remote.create <git.remote.Remote.create>` method.
 
-        :return: :class:`Remote <git.remote.Remote>` reference
+        :return: :class:`~git.remote.Remote` reference
         """
         return Remote.create(self, name, url, **kwargs)
 
@@ -599,8 +599,8 @@ def config_reader(
     ) -> GitConfigParser:
         """
         :return:
-            :class:`GitConfigParser <git.config.GitConfigParser>` allowing to read the
-            full git configuration, but not to write it.
+            :class:`~git.config.GitConfigParser` allowing to read the full git
+            configuration, but not to write it.
 
             The configuration will include values from the system, user and repository
             configuration files.
@@ -633,11 +633,10 @@ def _config_reader(
     def config_writer(self, config_level: Lit_config_levels = "repository") -> GitConfigParser:
         """
         :return:
-            A :class:`GitConfigParser <git.config.GitConfigParser>` allowing to write
-            values of the specified configuration file level. Config writers should be
-            retrieved, used to change the configuration, and written right away as they
-            will lock the configuration file in question and prevent other's to write
-            it.
+            A :class:`~git.config.GitConfigParser` allowing to write values of the
+            specified configuration file level. Config writers should be retrieved, used
+            to change the configuration, and written right away as they will lock the
+            configuration file in question and prevent other's to write it.
 
         :param config_level:
             One of the following values:
@@ -720,10 +719,10 @@ def merge_base(self, *rev: TBD, **kwargs: Any) -> List[Union[Commit_ish, None]]:
         :param rev: At least two revs to find the common ancestor for.
         :param kwargs: Additional arguments to be passed to the
             ``repo.git.merge_base()`` command which does all the work.
-        :return: A list of :class:`Commit <git.objects.commit.Commit>` objects. If
-            ``--all`` was not passed as a keyword argument, the list will have at max
-            one :class:`Commit <git.objects.commit.Commit>`, or is empty if no common
-            merge base exists.
+        :return: A list of :class:`~git.objects.commit.Commit` objects. If ``--all`` was
+            not passed as a keyword argument, the list will have at max one
+            :class:`~git.objects.commit.Commit`, or is empty if no common merge base
+            exists.
         :raises ValueError: If not at least two revs are provided.
         """
         if len(rev) < 2: