Repository navigation
Commit a040edb
committed
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
9 files changed
Lines changed: 70 additions & 69 deletions
File tree
- git
- objects
- submodule
- refs
- repo
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -118,12 +118,12 @@ def diff( | |||
| 118 | 118 | This the item to compare us with. | |
| 119 | 119 | ||
| 120 | 120 | * 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. | ||
| 124 | 124 | * 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. | ||
| 127 | 127 | ||
| 128 | 128 | :param paths: | |
| 129 | 129 | This a list of paths or a single path to limit the diff to. It will only | |
@@ -141,11 +141,9 @@ def diff( | |||
| 141 | 141 | :return: git.DiffIndex | |
| 142 | 142 | ||
| 143 | 143 | :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. | ||
| 149 | 147 | """ | |
| 150 | 148 | args: List[Union[PathLike, Diffable, Type["Diffable.Index"], object]] = [] | |
| 151 | 149 | args.append("--abbrev=40") # We need full shas. | |
@@ -222,7 +220,7 @@ class DiffIndex(List[T_Diff]): | |||
| 222 | 220 | def iter_change_type(self, change_type: Lit_change_type) -> Iterator[T_Diff]: | |
| 223 | 221 | """ | |
| 224 | 222 | :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` | ||
| 226 | 224 | ||
| 227 | 225 | :param change_type: | |
| 228 | 226 | Member of :attr:`DiffIndex.change_type`, namely: | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -178,7 +178,7 @@ def __init__( | |||
| 178 | 178 | ) -> None: | |
| 179 | 179 | """Initialize a newly instanced IndexObject. | |
| 180 | 180 | ||
| 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. | ||
| 182 | 182 | :param binsha: 20 byte sha1. | |
| 183 | 183 | :param mode: | |
| 184 | 184 | The stat compatible file mode as int, use the :mod:`stat` module to evaluate | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -113,14 +113,16 @@ def __init__( | |||
| 113 | 113 | ) -> None: | |
| 114 | 114 | """Initialize this instance with its attributes. | |
| 115 | 115 | ||
| 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. | ||
| 124 | 126 | """ | |
| 125 | 127 | super(Submodule, self).__init__(repo, binsha, mode, path) | |
| 126 | 128 | self.size = 0 | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -231,8 +231,8 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]: | |||
| 231 | 231 | ||
| 232 | 232 | :param force: | |
| 233 | 233 | 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. | ||
| 236 | 236 | ||
| 237 | 237 | :param kwargs: | |
| 238 | 238 | Additional keyword arguments to be passed to git checkout, e.g. | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -40,8 +40,8 @@ def wrapper(self: T_References, *args: Any) -> _T: | |||
| 40 | 40 | class Reference(SymbolicReference, LazyMixin, IterableObj): | |
| 41 | 41 | """A named reference to any object. | |
| 42 | 42 | ||
| 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. | ||
| 45 | 45 | """ | |
| 46 | 46 | ||
| 47 | 47 | __slots__ = () | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -59,7 +59,7 @@ class SymbolicReference: | |||
| 59 | 59 | """Special case of a reference that is symbolic. | |
| 60 | 60 | ||
| 61 | 61 | 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. | ||
| 63 | 63 | ||
| 64 | 64 | A typical example for a symbolic reference is ``HEAD``. | |
| 65 | 65 | """ | |
@@ -345,7 +345,7 @@ def set_object( | |||
| 345 | 345 | If the reference does not exist, it will be created. | |
| 346 | 346 | ||
| 347 | 347 | :param object: A refspec, a :class:`SymbolicReference` or an | |
| 348 | - :class:`Object <git.objects.base.Object>` instance. | ||
| 348 | + :class:`~git.objects.base.Object` instance. | ||
| 349 | 349 | :class:`SymbolicReference` instances will be dereferenced beforehand to | |
| 350 | 350 | obtain the object they point to. | |
| 351 | 351 | :param logmsg: If not None, the message will be used in the reflog entry to be | |
@@ -396,10 +396,10 @@ def set_reference( | |||
| 396 | 396 | symbolic one. | |
| 397 | 397 | ||
| 398 | 398 | :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. | ||
| 403 | 403 | ||
| 404 | 404 | :param logmsg: If set to a string, the message will be used in the reflog. | |
| 405 | 405 | Otherwise, a reflog entry is not written for the changed reference. | |
@@ -514,7 +514,7 @@ def log_append( | |||
| 514 | 514 | :param message: A message describing the change. | |
| 515 | 515 | :param newbinsha: The sha the ref points to now. If None, our current commit sha | |
| 516 | 516 | will be used. | |
| 517 | - :return: The added :class:`RefLogEntry <git.refs.log.RefLogEntry>` instance. | ||
| 517 | + :return: The added :class:`~git.refs.log.RefLogEntry` instance. | ||
| 518 | 518 | """ | |
| 519 | 519 | # NOTE: We use the committer of the currently active commit - this should be | |
| 520 | 520 | # correct to allow overriding the committer on a per-commit level. | |
@@ -540,7 +540,7 @@ def log_entry(self, index: int) -> "RefLogEntry": | |||
| 540 | 540 | ||
| 541 | 541 | .. note:: This method must read part of the reflog during execution, hence | |
| 542 | 542 | 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. | ||
| 544 | 544 | """ | |
| 545 | 545 | return RefLog.entry_at(RefLog.path(self), index) | |
| 546 | 546 | ||
@@ -816,8 +816,8 @@ def iter_items( | |||
| 816 | 816 | which is not detached and pointing to a valid ref. | |
| 817 | 817 | ||
| 818 | 818 | 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`. | ||
| 821 | 821 | """ | |
| 822 | 822 | return (r for r in cls._iter_items(repo, common_path) if r.__class__ is SymbolicReference or not r.is_detached) | |
| 823 | 823 | ||
@@ -826,14 +826,16 @@ def from_path(cls: Type[T_References], repo: "Repo", path: PathLike) -> T_Refere | |||
| 826 | 826 | """ | |
| 827 | 827 | Make a symbolic reference from a path. | |
| 828 | 828 | ||
| 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. | ||
| 830 | 831 | ||
| 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. | ||
| 832 | 834 | ||
| 833 | 835 | :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. | ||
| 837 | 839 | """ | |
| 838 | 840 | if not path: | |
| 839 | 841 | raise ValueError("Cannot create Reference from %r" % path) | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -89,8 +89,8 @@ def create( | |||
| 89 | 89 | The prefix ``refs/tags`` is implied. | |
| 90 | 90 | ||
| 91 | 91 | :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. | ||
| 94 | 94 | ||
| 95 | 95 | :param logmsg: | |
| 96 | 96 | If not None, the message will be used in your tag object. This will also | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -210,9 +210,9 @@ def old_commit(self) -> Union[str, SymbolicReference, Commit_ish, None]: | |||
| 210 | 210 | def remote_ref(self) -> Union[RemoteReference, TagReference]: | |
| 211 | 211 | """ | |
| 212 | 212 | :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. | ||
| 216 | 216 | """ | |
| 217 | 217 | # Translate heads to a local remote. Tags stay as they are. | |
| 218 | 218 | if self.remote_ref_string.startswith("refs/tags"): | |
@@ -1093,7 +1093,7 @@ def push( | |||
| 1093 | 1093 | `Click here <http://goo.gl/NPa7st>`__ for a description of all arguments | |
| 1094 | 1094 | given to the function. | |
| 1095 | 1095 | * 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. | ||
| 1097 | 1097 | ||
| 1098 | 1098 | :note: No further progress information is returned after push returns. | |
| 1099 | 1099 | ||
@@ -1109,14 +1109,14 @@ def push( | |||
| 1109 | 1109 | :param kwargs: Additional arguments to be passed to git-push. | |
| 1110 | 1110 | ||
| 1111 | 1111 | :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. | ||
| 1114 | 1114 | If the push contains rejected heads, these will have the | |
| 1115 | 1115 | :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. | ||
| 1120 | 1120 | """ | |
| 1121 | 1121 | kwargs = add_progress(kwargs, self.repo.git, progress) | |
| 1122 | 1122 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -387,7 +387,7 @@ def heads(self) -> "IterableList[Head]": | |||
| 387 | 387 | def references(self) -> "IterableList[Reference]": | |
| 388 | 388 | """A list of Reference objects representing tags, heads and remote references. | |
| 389 | 389 | ||
| 390 | - :return: IterableList(Reference, ...) | ||
| 390 | + :return: ``git.IterableList(Reference, ...)`` | ||
| 391 | 391 | """ | |
| 392 | 392 | return Reference.list_items(self) | |
| 393 | 393 | ||
@@ -400,11 +400,11 @@ def references(self) -> "IterableList[Reference]": | |||
| 400 | 400 | @property | |
| 401 | 401 | def index(self) -> "IndexFile": | |
| 402 | 402 | """ | |
| 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. | ||
| 405 | 405 | ||
| 406 | 406 | :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. | ||
| 408 | 408 | It is recommended to reuse the object. | |
| 409 | 409 | """ | |
| 410 | 410 | return IndexFile(self) | |
@@ -520,7 +520,7 @@ def create_head( | |||
| 520 | 520 | :note: For more documentation, please see the | |
| 521 | 521 | :meth:`Head.create <git.refs.head.Head.create>` method. | |
| 522 | 522 | ||
| 523 | - :return: Newly created :class:`Head <git.refs.head.Head>` Reference | ||
| 523 | + :return: Newly created :class:`~git.refs.head.Head` Reference | ||
| 524 | 524 | """ | |
| 525 | 525 | return Head.create(self, path, commit, logmsg, force) | |
| 526 | 526 | ||
@@ -544,7 +544,7 @@ def create_tag( | |||
| 544 | 544 | :note: For more documentation, please see the | |
| 545 | 545 | :meth:`TagReference.create <git.refs.tag.TagReference.create>` method. | |
| 546 | 546 | ||
| 547 | - :return: :class:`TagReference <git.refs.tag.TagReference>` object | ||
| 547 | + :return: :class:`~git.refs.tag.TagReference` object | ||
| 548 | 548 | """ | |
| 549 | 549 | return TagReference.create(self, path, ref, message, force, **kwargs) | |
| 550 | 550 | ||
@@ -558,7 +558,7 @@ def create_remote(self, name: str, url: str, **kwargs: Any) -> Remote: | |||
| 558 | 558 | For more information, please see the documentation of the | |
| 559 | 559 | :meth:`Remote.create <git.remote.Remote.create>` method. | |
| 560 | 560 | ||
| 561 | - :return: :class:`Remote <git.remote.Remote>` reference | ||
| 561 | + :return: :class:`~git.remote.Remote` reference | ||
| 562 | 562 | """ | |
| 563 | 563 | return Remote.create(self, name, url, **kwargs) | |
| 564 | 564 | ||
@@ -599,8 +599,8 @@ def config_reader( | |||
| 599 | 599 | ) -> GitConfigParser: | |
| 600 | 600 | """ | |
| 601 | 601 | :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. | ||
| 604 | 604 | ||
| 605 | 605 | The configuration will include values from the system, user and repository | |
| 606 | 606 | configuration files. | |
@@ -633,11 +633,10 @@ def _config_reader( | |||
| 633 | 633 | def config_writer(self, config_level: Lit_config_levels = "repository") -> GitConfigParser: | |
| 634 | 634 | """ | |
| 635 | 635 | :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. | ||
| 641 | 640 | ||
| 642 | 641 | :param config_level: | |
| 643 | 642 | One of the following values: | |
@@ -720,10 +719,10 @@ def merge_base(self, *rev: TBD, **kwargs: Any) -> List[Union[Commit_ish, None]]: | |||
| 720 | 719 | :param rev: At least two revs to find the common ancestor for. | |
| 721 | 720 | :param kwargs: Additional arguments to be passed to the | |
| 722 | 721 | ``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. | ||
| 727 | 726 | :raises ValueError: If not at least two revs are provided. | |
| 728 | 727 | """ | |
| 729 | 728 | if len(rev) < 2: | |
0 commit comments