Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit a040edb

Browse files
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.)
1 parent 81dad7e commit a040edb

File tree

9 files changed

+70
-69
lines changed

9 files changed

+70
-69
lines changed

‎git/diff.py‎

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -118,12 +118,12 @@ def diff(
118118
This the item to compare us with.
119119
120120
* If None, we will be compared to the working tree.
121-
* If :class:`Treeish <git.index.base.Treeish>`, it will be compared against
122-
the respective tree.
123-
* If :class:`Index <Diffable.Index>`, it will be compared against the index.
121+
* If :class:`~git.index.base.Treeish`, it will be compared against the
122+
respective tree.
123+
* If :class:`~Diffable.Index`, it will be compared against the index.
124124
* If :attr:`git.NULL_TREE`, it will compare against the empty tree.
125-
* It defaults to :class:`Index <Diffable.Index>` so that the method will not
126-
by default fail on bare repositories.
125+
* It defaults to :class:`~Diffable.Index` so that the method will not by
126+
default fail on bare repositories.
127127
128128
:param paths:
129129
This a list of paths or a single path to limit the diff to. It will only
@@ -141,11 +141,9 @@ def diff(
141141
:return: git.DiffIndex
142142
143143
:note:
144-
On a bare repository, 'other' needs to be provided
145-
as :class:`Index <Diffable.Index>`,
146-
or as :class:`Tree <git.objects.tree.Tree>`
147-
or :class:`Commit <git.objects.commit.Commit>`, or a git command error will
148-
occur.
144+
On a bare repository, 'other' needs to be provided as
145+
:class:`~Diffable.Index`, or as :class:`~git.objects.tree.Tree` or
146+
:class:`~git.objects.commit.Commit`, or a git command error will occur.
149147
"""
150148
args: List[Union[PathLike, Diffable, Type["Diffable.Index"], object]] = []
151149
args.append("--abbrev=40") # We need full shas.
@@ -222,7 +220,7 @@ class DiffIndex(List[T_Diff]):
222220
def iter_change_type(self, change_type: Lit_change_type) -> Iterator[T_Diff]:
223221
"""
224222
:return:
225-
iterator yielding :class:`Diff` instances that match the given `change_type`
223+
Iterator yielding :class:`Diff` instances that match the given `change_type`
226224
227225
:param change_type:
228226
Member of :attr:`DiffIndex.change_type`, namely:

‎git/objects/base.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ def __init__(
178178
) -> None:
179179
"""Initialize a newly instanced IndexObject.
180180
181-
:param repo: The :class:`Repo <git.repo.base.Repo>` we are located in.
181+
:param repo: The :class:`~git.repo.base.Repo` we are located in.
182182
:param binsha: 20 byte sha1.
183183
:param mode:
184184
The stat compatible file mode as int, use the :mod:`stat` module to evaluate

‎git/objects/submodule/base.py‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -113,14 +113,16 @@ def __init__(
113113
) -> None:
114114
"""Initialize this instance with its attributes.
115115
116-
We only document the parameters that differ
117-
from :class:`IndexObject <git.objects.base.IndexObject>`.
118-
119-
:param repo: Our parent repository
120-
:param binsha: binary sha referring to a commit in the remote repository, see url parameter
121-
:param parent_commit: see set_parent_commit()
122-
:param url: The url to the remote repository which is the submodule
123-
:param branch_path: full (relative) path to ref to checkout when cloning the remote repository
116+
We only document the parameters that differ from
117+
:class:`~git.objects.base.IndexObject`.
118+
119+
:param repo: Our parent repository.
120+
:param binsha: Binary sha referring to a commit in the remote repository. See
121+
the ``url`` parameter.
122+
:param parent_commit: See :meth:`set_parent_commit`.
123+
:param url: The URL to the remote repository which is the submodule.
124+
:param branch_path: Full (relative) path to ref to checkout when cloning the
125+
remote repository.
124126
"""
125127
super(Submodule, self).__init__(repo, binsha, mode, path)
126128
self.size = 0

‎git/refs/head.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -231,8 +231,8 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
231231
232232
:param force:
233233
If True, changes to the index and the working tree will be discarded.
234-
If False, :class:`GitCommandError <git.exc.GitCommandError>` will be
235-
raised in that situation.
234+
If False, :class:`~git.exc.GitCommandError` will be raised in that
235+
situation.
236236
237237
:param kwargs:
238238
Additional keyword arguments to be passed to git checkout, e.g.

‎git/refs/reference.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ def wrapper(self: T_References, *args: Any) -> _T:
4040
class Reference(SymbolicReference, LazyMixin, IterableObj):
4141
"""A named reference to any object.
4242
43-
Subclasses may apply restrictions though, e.g., a :class:`Head <git.refs.head.Head>`
44-
can only point to commits.
43+
Subclasses may apply restrictions though, e.g., a :class:`~git.refs.head.Head` can
44+
only point to commits.
4545
"""
4646

4747
__slots__ = ()

‎git/refs/symbolic.py‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ class SymbolicReference:
5959
"""Special case of a reference that is symbolic.
6060
6161
This does not point to a specific commit, but to another
62-
:class:`Head <git.refs.head.Head>`, which itself specifies a commit.
62+
:class:`~git.refs.head.Head`, which itself specifies a commit.
6363
6464
A typical example for a symbolic reference is ``HEAD``.
6565
"""
@@ -345,7 +345,7 @@ def set_object(
345345
If the reference does not exist, it will be created.
346346
347347
:param object: A refspec, a :class:`SymbolicReference` or an
348-
:class:`Object <git.objects.base.Object>` instance.
348+
:class:`~git.objects.base.Object` instance.
349349
:class:`SymbolicReference` instances will be dereferenced beforehand to
350350
obtain the object they point to.
351351
:param logmsg: If not None, the message will be used in the reflog entry to be
@@ -396,10 +396,10 @@ def set_reference(
396396
symbolic one.
397397
398398
:param ref:
399-
A :class:`SymbolicReference` instance,
400-
an :class:`Object <git.objects.base.Object>` instance, or a refspec string.
401-
Only if the ref is a :class:`SymbolicReference` instance, we will point to
402-
it. Everything else is dereferenced to obtain the actual object.
399+
A :class:`SymbolicReference` instance, an :class:`~git.objects.base.Object`
400+
instance, or a refspec string. Only if the ref is a
401+
:class:`SymbolicReference` instance, we will point to it. Everything else is
402+
dereferenced to obtain the actual object.
403403
404404
:param logmsg: If set to a string, the message will be used in the reflog.
405405
Otherwise, a reflog entry is not written for the changed reference.
@@ -514,7 +514,7 @@ def log_append(
514514
:param message: A message describing the change.
515515
:param newbinsha: The sha the ref points to now. If None, our current commit sha
516516
will be used.
517-
:return: The added :class:`RefLogEntry <git.refs.log.RefLogEntry>` instance.
517+
:return: The added :class:`~git.refs.log.RefLogEntry` instance.
518518
"""
519519
# NOTE: We use the committer of the currently active commit - this should be
520520
# correct to allow overriding the committer on a per-commit level.
@@ -540,7 +540,7 @@ def log_entry(self, index: int) -> "RefLogEntry":
540540
541541
.. note:: This method must read part of the reflog during execution, hence
542542
it should be used sparingly, or only if you need just one index.
543-
In that case, it will be faster than the ``log()`` method.
543+
In that case, it will be faster than the :meth:`log` method.
544544
"""
545545
return RefLog.entry_at(RefLog.path(self), index)
546546

@@ -816,8 +816,8 @@ def iter_items(
816816
which is not detached and pointing to a valid ref.
817817
818818
The list is lexicographically sorted. The returned objects are instances of
819-
concrete subclasses, such as :class:`Head <git.refs.head.Head>` or
820-
:class:`TagReference <git.refs.tag.TagReference>`.
819+
concrete subclasses, such as :class:`~git.refs.head.Head` or
820+
:class:`~git.refs.tag.TagReference`.
821821
"""
822822
return (r for r in cls._iter_items(repo, common_path) if r.__class__ is SymbolicReference or not r.is_detached)
823823

@@ -826,14 +826,16 @@ def from_path(cls: Type[T_References], repo: "Repo", path: PathLike) -> T_Refere
826826
"""
827827
Make a symbolic reference from a path.
828828
829-
:param path: Full ``.git``-directory-relative path name to the Reference to instantiate.
829+
:param path: Full ``.git``-directory-relative path name to the Reference to
830+
instantiate.
830831
831-
:note: Use :meth:`to_full_path` if you only have a partial path of a known Reference type.
832+
:note: Use :meth:`to_full_path` if you only have a partial path of a known
833+
Reference type.
832834
833835
:return:
834-
Instance of type :class:`Reference <git.refs.reference.Reference>`,
835-
:class:`Head <git.refs.head.Head>`, or :class:`Tag <git.refs.tag.Tag>`,
836-
depending on the given path.
836+
Instance of type :class:`~git.refs.reference.Reference`,
837+
:class:`~git.refs.head.Head`, or :class:`~git.refs.tag.Tag`, depending on
838+
the given path.
837839
"""
838840
if not path:
839841
raise ValueError("Cannot create Reference from %r" % path)

‎git/refs/tag.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,8 +89,8 @@ def create(
8989
The prefix ``refs/tags`` is implied.
9090
9191
:param ref:
92-
A reference to the :class:`Object <git.objects.base.Object>` you want to
93-
tag. The Object can be a commit, tree or blob.
92+
A reference to the :class:`~git.objects.base.Object` you want to tag.
93+
The Object can be a commit, tree or blob.
9494
9595
:param logmsg:
9696
If not None, the message will be used in your tag object. This will also

‎git/remote.py‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -210,9 +210,9 @@ def old_commit(self) -> Union[str, SymbolicReference, Commit_ish, None]:
210210
def remote_ref(self) -> Union[RemoteReference, TagReference]:
211211
"""
212212
:return:
213-
Remote :class:`Reference <git.refs.reference.Reference>` or
214-
:class:`TagReference <git.refs.tag.TagReference>` in the local repository
215-
corresponding to the :attr:`remote_ref_string` kept in this instance.
213+
Remote :class:`~git.refs.reference.Reference` or
214+
:class:`~git.refs.tag.TagReference` in the local repository corresponding to
215+
the :attr:`remote_ref_string` kept in this instance.
216216
"""
217217
# Translate heads to a local remote. Tags stay as they are.
218218
if self.remote_ref_string.startswith("refs/tags"):
@@ -1093,7 +1093,7 @@ def push(
10931093
`Click here <http://goo.gl/NPa7st>`__ for a description of all arguments
10941094
given to the function.
10951095
* An instance of a class derived from :class:`git.RemoteProgress` that
1096-
overrides the :meth:`update <git.RemoteProgress.update>` method.
1096+
overrides the :meth:`~git.RemoteProgress.update` method.
10971097
10981098
:note: No further progress information is returned after push returns.
10991099
@@ -1109,14 +1109,14 @@ def push(
11091109
:param kwargs: Additional arguments to be passed to git-push.
11101110
11111111
:return:
1112-
A :class:`PushInfoList` object, where each list member
1113-
represents an individual head which had been updated on the remote side.
1112+
A :class:`PushInfoList` object, where each list member represents an
1113+
individual head which had been updated on the remote side.
11141114
If the push contains rejected heads, these will have the
11151115
:attr:`PushInfo.ERROR` bit set in their flags.
1116-
If the operation fails completely, the length of the returned PushInfoList will
1117-
be 0.
1118-
Call :meth:`raise_if_error <PushInfoList.raise_if_error>` on the returned
1119-
object to raise on any failure.
1116+
If the operation fails completely, the length of the returned PushInfoList
1117+
will be 0.
1118+
Call :meth:`~PushInfoList.raise_if_error` on the returned object to raise on
1119+
any failure.
11201120
"""
11211121
kwargs = add_progress(kwargs, self.repo.git, progress)
11221122

‎git/repo/base.py‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -387,7 +387,7 @@ def heads(self) -> "IterableList[Head]":
387387
def references(self) -> "IterableList[Reference]":
388388
"""A list of Reference objects representing tags, heads and remote references.
389389
390-
:return: IterableList(Reference, ...)
390+
:return: ``git.IterableList(Reference, ...)``
391391
"""
392392
return Reference.list_items(self)
393393

@@ -400,11 +400,11 @@ def references(self) -> "IterableList[Reference]":
400400
@property
401401
def index(self) -> "IndexFile":
402402
"""
403-
:return: :class:`IndexFile <git.index.base.IndexFile>` representing this
404-
repository's index.
403+
:return: A :class:`~git.index.base.IndexFile` representing this repository's
404+
index.
405405
406406
:note: This property can be expensive, as the returned
407-
:class:`IndexFile <git.index.base.IndexFile>` will be reinitialized.
407+
:class:`~git.index.base.IndexFile` will be reinitialized.
408408
It is recommended to reuse the object.
409409
"""
410410
return IndexFile(self)
@@ -520,7 +520,7 @@ def create_head(
520520
:note: For more documentation, please see the
521521
:meth:`Head.create <git.refs.head.Head.create>` method.
522522
523-
:return: Newly created :class:`Head <git.refs.head.Head>` Reference
523+
:return: Newly created :class:`~git.refs.head.Head` Reference
524524
"""
525525
return Head.create(self, path, commit, logmsg, force)
526526

@@ -544,7 +544,7 @@ def create_tag(
544544
:note: For more documentation, please see the
545545
:meth:`TagReference.create <git.refs.tag.TagReference.create>` method.
546546
547-
:return: :class:`TagReference <git.refs.tag.TagReference>` object
547+
:return: :class:`~git.refs.tag.TagReference` object
548548
"""
549549
return TagReference.create(self, path, ref, message, force, **kwargs)
550550

@@ -558,7 +558,7 @@ def create_remote(self, name: str, url: str, **kwargs: Any) -> Remote:
558558
For more information, please see the documentation of the
559559
:meth:`Remote.create <git.remote.Remote.create>` method.
560560
561-
:return: :class:`Remote <git.remote.Remote>` reference
561+
:return: :class:`~git.remote.Remote` reference
562562
"""
563563
return Remote.create(self, name, url, **kwargs)
564564

@@ -599,8 +599,8 @@ def config_reader(
599599
) -> GitConfigParser:
600600
"""
601601
:return:
602-
:class:`GitConfigParser <git.config.GitConfigParser>` allowing to read the
603-
full git configuration, but not to write it.
602+
:class:`~git.config.GitConfigParser` allowing to read the full git
603+
configuration, but not to write it.
604604
605605
The configuration will include values from the system, user and repository
606606
configuration files.
@@ -633,11 +633,10 @@ def _config_reader(
633633
def config_writer(self, config_level: Lit_config_levels = "repository") -> GitConfigParser:
634634
"""
635635
:return:
636-
A :class:`GitConfigParser <git.config.GitConfigParser>` allowing to write
637-
values of the specified configuration file level. Config writers should be
638-
retrieved, used to change the configuration, and written right away as they
639-
will lock the configuration file in question and prevent other's to write
640-
it.
636+
A :class:`~git.config.GitConfigParser` allowing to write values of the
637+
specified configuration file level. Config writers should be retrieved, used
638+
to change the configuration, and written right away as they will lock the
639+
configuration file in question and prevent other's to write it.
641640
642641
:param config_level:
643642
One of the following values:
@@ -720,10 +719,10 @@ def merge_base(self, *rev: TBD, **kwargs: Any) -> List[Union[Commit_ish, None]]:
720719
:param rev: At least two revs to find the common ancestor for.
721720
:param kwargs: Additional arguments to be passed to the
722721
``repo.git.merge_base()`` command which does all the work.
723-
:return: A list of :class:`Commit <git.objects.commit.Commit>` objects. If
724-
``--all`` was not passed as a keyword argument, the list will have at max
725-
one :class:`Commit <git.objects.commit.Commit>`, or is empty if no common
726-
merge base exists.
722+
:return: A list of :class:`~git.objects.commit.Commit` objects. If ``--all`` was
723+
not passed as a keyword argument, the list will have at max one
724+
:class:`~git.objects.commit.Commit`, or is empty if no common merge base
725+
exists.
727726
:raises ValueError: If not at least two revs are provided.
728727
"""
729728
if len(rev) < 2:

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /