-
-
Notifications
You must be signed in to change notification settings - Fork 902
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Revise docstrings, comments, and a few messages #1850
Commits on Feb 26, 2024
-
Fix typos and further clarify Git.refresh docstring
This further improves the text previously introduced in gitpython-developers#1829 and improved in gitpython-developers#1844.
Configuration menu - View commit details
-
Copy full SHA for 9b5531b - Browse repository at this point
Copy the full SHA 9b5531bView commit details -
Configuration menu - View commit details
-
Copy full SHA for c0cd8a8 - Browse repository at this point
Copy the full SHA c0cd8a8View commit details -
Tweak message about GIT_PYTHON_REFRESH for 80-column terminals
The fragment of the refresh failure message (which is often written to a terminal) about the effect of setting GIT_PYTHON_REFRESH to control refesh failure reporting had previously been formatted with a maximum line length of 79 columns--in the message itself, not the code for the message--so that it would fit in a traditional 80 column wide terminal. This remains one of the popular widths to set for terminal windows in a GUI, so it seems worthwhile to preserve. In 3a6e3ef (gitpython-developers#1815), I had inadvertently made the line one character too long for that; at 80 columns, it would cause the newline to be written at the start of the next line, creating an unsightly extra line break. This is pretty minor, but what seems to me like an equally good alternative wording avoids it, so this commit shortens the wording.
Configuration menu - View commit details
-
Copy full SHA for afd943a - Browse repository at this point
Copy the full SHA afd943aView commit details -
Revise docstrings in git.__init__ and git.cmd
Mainly for formatting.
Configuration menu - View commit details
-
Copy full SHA for e08066c - Browse repository at this point
Copy the full SHA e08066cView commit details -
Configuration menu - View commit details
-
Copy full SHA for 8bb882e - Browse repository at this point
Copy the full SHA 8bb882eView commit details -
Reword partial_to_complete_sha_hex note
The git.db.partial_to_complete_sha_hex docstring refers to "AmbiguousObjects", suggesting the existence of an AmbiguousObject type (or an AmbiguousObjects type). Since there appears to be no such type in GitPython (or in gitdb), this seems to have been written in reference to the condition expressed by the AmbiguousObjectName exception, which the note says is not currently able to be raised (such that BadObject is raised instead) in situations where it would apply. Since the connection to that exeception is already clear from context, this commit changes the wording to "ambiguous objects" to avoid being misread as a reference to a Python class of ambiguous objects.
Configuration menu - View commit details
-
Copy full SHA for ba878ef - Browse repository at this point
Copy the full SHA ba878efView commit details -
Update CommandError._msg documentation
This converts it from a specially formatted comment to a docstring (gitpython-developers#1734), rewords for clarity, and removes the mention of unicode, which appears to have been referring to the data type. (GitPython no longer supports Python 2, and unicode is not a separate type from str in Python 3, where instead str and bytes are different types.)
Configuration menu - View commit details
-
Copy full SHA for 3958747 - Browse repository at this point
Copy the full SHA 3958747View commit details -
Tweak code formatting in Remote._set_cache_
For slightly easier reading.
Configuration menu - View commit details
-
Copy full SHA for f56e1ac - Browse repository at this point
Copy the full SHA f56e1acView commit details -
- Replace the goo.gl web shortlink with a Sphinx reference that displays and also (in built documentation) becomes a hyperlink to the documentation on the method being referred to. - Refer to a related class (which is in another module) as being in the module where it is defined, rather than in the top-level git module (where it also can be accessed because it is imported there, which is reasonable to do, but less clear documentation). - Tweak punctuation so the effect of passing None is a bit clearer.
Configuration menu - View commit details
-
Copy full SHA for fa471fe - Browse repository at this point
Copy the full SHA fa471feView commit details -
Revise docstrings in second-level modules
Except for: - git.cmd, where docstrings were revised in e08066c. - git.types, where docstring changes may best be made together with changes to how imports are organized and documented, which seems not to be in the same scope as the changes in this commit. This change, as well as those in e08066c, are largely along the lines of gitpython-developers#1725, with most revisions here being to docstrings and a few being to comments. The major differences between the kinds of docstring changes here and those ind gitpython-developers#1725 are that the changes here push somewhat harder for consistency and apply some kinds of changes I was reluctant to apply widely in gitpython-developers#1725: - Wrap all docstrings and comments to 88 columns, except for parts that are decisively clearer when not wrapped. Note that semi- paragraph changes represented as single newlines are still kept where meaningful, which is one reason this is not always the same effect as automatic wrapping would produce. - Avoid code formatting (double backticks) for headings that precede sections and code blocks. This was done enough that it seems to have been intentional, but it doesn't really have the right semantics, and the documentation is currently rendering in such a way (including on readthedocs.org) where removing that formatting seems clearly better. - References (single backticks with a role prefix) and code spans (double backticks) everywhere applicable, even in the first lines of docstrings. - Single-backticks around parameter names, with no role prefix. These were mostly either formatted that way or emphasized (with asterisks). This is one of the rare cases that I have used single backticks without a role prefix, which ordinarily should be avoided, but to get a role for references to a function's parameters within that function, a plugin would be needed. In the rare case that one function's docstring refers to another function's parameters by names those are double-backticked as code spans (and where applicable the name of the referred-to function is single-backticked with the :func: or :meth: role). - All sections, such as :param blah:, :note:, and :return:, now have a newline before any text in them. This was already often but far from always done, and the style was overall inconsistent. Of consistent approaches that are clear and easy to write, this is the simplest. It also seems to substantially improve readability, when taken together with... - Sections are always separated by a blank line, even if they are very short. - Essentially unlimited use of `~a.b.c`, where applicable, to refer and link to the documentation for a.b.c while showing the text "a" and revealing "a.b.c" on hover. I had previously somewhat limited my use of this tilde notation in case readers of the source code itself (where it is not rendered) weren't familiar with it, but at the cost of less consistency in when an entity was referred to. There remain a couple places in git.util where I do not do this because the explicit form `a <a.b.c>`, which is equivalent, lined things up better and was thus easier to read. Those are the major differences between the approach taken here and in gitpython-developers#1725, but not necessarily most of the changes done here (many of which are the same kinds of revisions as done there). Note that this commit only modifies some git/*.py files, and there are more git/**/*.py files that remain to be revised accordingly.
Configuration menu - View commit details
-
Copy full SHA for 1cd73ba - Browse repository at this point
Copy the full SHA 1cd73baView commit details -
Format first Git.execute overload stub like the others
This makes it easier to read along with, and compare to, the other overloads.
Configuration menu - View commit details
-
Copy full SHA for 29c63ac - Browse repository at this point
Copy the full SHA 29c63acView commit details -
Show full-path refresh() in failure message differently
This presents it more symbolically, rather than in an example-like style that could confuse. See discussion in gitpython-developers#1844.
Configuration menu - View commit details
-
Copy full SHA for cd8a312 - Browse repository at this point
Copy the full SHA cd8a312View commit details -
Configuration menu - View commit details
-
Copy full SHA for 8ec7e32 - Browse repository at this point
Copy the full SHA 8ec7e32View commit details -
So that it just describes the current situation, rather than suggesting a future direction for IndexFile. This is for gitpython-developers#1847.
Configuration menu - View commit details
-
Copy full SHA for ca2ab61 - Browse repository at this point
Copy the full SHA ca2ab61View commit details -
Further revise post_clear_cache docstring
For gitpython-developers#1847. This removes the note, and splits out some related material from the docstring's top line into a second paragraph for readability (since the first sentence of the top line was complete, and described usage).
Configuration menu - View commit details
-
Copy full SHA for 37421e1 - Browse repository at this point
Copy the full SHA 37421e1View commit details -
Configuration menu - View commit details
-
Copy full SHA for ca32c22 - Browse repository at this point
Copy the full SHA ca32c22View commit details -
Clarify Submodule.branch_path documentation
This changes "Full (relative) path" to "Complete relative path" in the wording used to describe the branch_path initializer parameter and property of the Submodule class. This is to prevent confusion, since "full path" means something like "absolute path" (and is now used as such in error messages introduced since these docstrings were last edited).
Configuration menu - View commit details
-
Copy full SHA for 3813bfb - Browse repository at this point
Copy the full SHA 3813bfbView commit details
Commits on Feb 27, 2024
-
Configuration menu - View commit details
-
Copy full SHA for 63c62ed - Browse repository at this point
Copy the full SHA 63c62edView commit details -
Change _write to write in SubmoduleConfigParser docstring
Since it appears to refer to the write method, which it overrides, rather that the nonpublic _write method (which is not overridden, and whose direct calls are not affected).
Configuration menu - View commit details
-
Copy full SHA for 115451d - Browse repository at this point
Copy the full SHA 115451dView commit details -
Fix IndexObject.abspath docstring formatting
The original problem where the backslash wasn't included in the docstring at all was fixed in 7dd2095 (gitpython-developers#1725), but the backslash still did not appear in rendered Sphinx documentation, because it was also treated as a reStructuredText metacharacter. Although that can be addressed by adding a further backslash to escape it, the effect is ambiguous when the docstring is read in the code. So this just encloses it in a double-backticked code span instead, which is a somewhat clearer way to show it anyway.
Configuration menu - View commit details
-
Copy full SHA for 5219489 - Browse repository at this point
Copy the full SHA 5219489View commit details -
Configuration menu - View commit details
-
Copy full SHA for c06dfd9 - Browse repository at this point
Copy the full SHA c06dfd9View commit details -
Revise docstrings within git.objects
But not within git.objects.submodule, which was done in 63c62ed.
Configuration menu - View commit details
-
Copy full SHA for ae37a4a - Browse repository at this point
Copy the full SHA ae37a4aView commit details -
Configuration menu - View commit details
-
Copy full SHA for 37011bf - Browse repository at this point
Copy the full SHA 37011bfView commit details -
Further git.util docstring revisions
That I had missed in 1cd73ba.
Configuration menu - View commit details
-
Copy full SHA for d9fb2f4 - Browse repository at this point
Copy the full SHA d9fb2f4View commit details -
Configuration menu - View commit details
-
Copy full SHA for d1d18c2 - Browse repository at this point
Copy the full SHA d1d18c2View commit details -
Fix backslashes in Repo.__init__ docstring
The example code block included a Windows-style path string written with doubled backslashes, but the docstring itself was not a raw string literal, so these collapsed into single backslashes. This makes the whole docstring an R-string, which is sufficient to solve that problem (since the backslashes are in a code block, Sphinx does not itself treat them as metacharacters). In addition, this changes the Windows-style path to be an R-string rather than using doubled backslashes. This is just to improve clarity (and remind readers they can use an R-string for Windows paths), and does not affect correctness.
Configuration menu - View commit details
-
Copy full SHA for 4f67369 - Browse repository at this point
Copy the full SHA 4f67369View commit details -
Fix Repo.iter_commits docstring about return type
It had said it returned a list of Commit objects, but it returns an iterator of Commit objects.
Configuration menu - View commit details
-
Copy full SHA for 0c8ca1a - Browse repository at this point
Copy the full SHA 0c8ca1aView commit details
Commits on Feb 28, 2024
-
Configuration menu - View commit details
-
Copy full SHA for b2b6f7c - Browse repository at this point
Copy the full SHA b2b6f7cView commit details -
Adjust spacing in colon seach mode NotImplementedError
This is a (very) minor improvement that uses the more common convention of not padding parentheses on the inside with spaces in prose, in an exception message.
Configuration menu - View commit details
-
Copy full SHA for c67b2e2 - Browse repository at this point
Copy the full SHA c67b2e2View commit details -
Update git source link in Repo.merge_base comment
And link to a specific tag (the most recent stable version tag) so the the hyperlink won't break in the future (as long as GitHub URLs keep working).
Configuration menu - View commit details
-
Copy full SHA for 5ee8744 - Browse repository at this point
Copy the full SHA 5ee8744View commit details -
Configuration menu - View commit details
-
Copy full SHA for c8b6cf0 - Browse repository at this point
Copy the full SHA c8b6cf0View commit details -
Fix recent inconsistency, using :raise:, not :raises:
GitPython used :raise: consistently before, but I recently introduced some occurrences of :raises: by accident. This changes those to :raise:.
Configuration menu - View commit details
-
Copy full SHA for bcc0c27 - Browse repository at this point
Copy the full SHA bcc0c27View commit details -
Further revise docstrings in git.objects.submodule.base
I had missed a lot of stuff there in 63c62ed.
Configuration menu - View commit details
-
Copy full SHA for 0231b74 - Browse repository at this point
Copy the full SHA 0231b74View commit details -
Configuration menu - View commit details
-
Copy full SHA for 8344f44 - Browse repository at this point
Copy the full SHA 8344f44View commit details -
Configuration menu - View commit details
-
Copy full SHA for 432ec72 - Browse repository at this point
Copy the full SHA 432ec72View commit details -
Fully qualify non-builtin exceptions in :raise:
This expands exceptions from git.exc and gitdb.exc in :raise: sections of docstrings, to include those qualifiers. This serves a few purposes. The main benefits are: - Immediately clarify which exceptions are not built-in ones, as not all readers are necessarily familiar with all built-in exceptions. - Distinguish exceptions defined in GitPython (in git.exc) from those defined in gitdb (in gitdb.exc). Although the gitdb exceptions GitPython uses are imported into git.exc and listed in __all__, they are still not introduced in GitPython, which is relevant for (a) preventing confusion, so developers don't think they accidentally imported a different same-named exception, (b) understanding why they do not have documentation in the generated GitPython docs. It also has these minor benefits: - May help sphinx-autodoc find them. In practice I think this is unlikely to be necessary. - Most other references, including references to classes, within docstrings in the git module, are now fully qualified, when not defined/introduced in the same module. So this is consistent with that. This consistency might be more than a minor benefit if there were a committment to keep most such refernces fully qualified, but this really should not be a goal: especially where Sphinx autodoc is guaranteed to be able to resolve them, shortening (in some cases, re-shortening) the references in the future may lead to better docstring readability.
Configuration menu - View commit details
-
Copy full SHA for 5ca5844 - Browse repository at this point
Copy the full SHA 5ca5844View commit details -
Configuration menu - View commit details
-
Copy full SHA for e6768ec - Browse repository at this point
Copy the full SHA e6768ecView commit details -
Further revise docstrings in second-level modules
Some stuff unintentionally missed in 1cd73ba and some subsequent commits, plus a few further things intentionally omitted there, such as converting True, False, and None literals, to double backticked form (rather than bare or single-backticked).
Configuration menu - View commit details
-
Copy full SHA for cd61eb4 - Browse repository at this point
Copy the full SHA cd61eb4View commit details -
Undo a couple minor black-incompatible changes
Two of the docstrings in git.remote need to have a newline before the conceptually "first" line in order for black to accept the indentation of the subsequent text, which appears intentional and works fine as reStructuredText. Otherwise black dedents the code block, which affects rendering and is also less readable.
Configuration menu - View commit details
-
Copy full SHA for fc1762b - Browse repository at this point
Copy the full SHA fc1762bView commit details -
Configuration menu - View commit details
-
Copy full SHA for 1b25a13 - Browse repository at this point
Copy the full SHA 1b25a13View commit details -
Configuration menu - View commit details
-
Copy full SHA for 08a80aa - Browse repository at this point
Copy the full SHA 08a80aaView commit details -
Configuration menu - View commit details
-
Copy full SHA for bc48d26 - Browse repository at this point
Copy the full SHA bc48d26View commit details -
Fix erroneous reference to DateTime "class"
DateTime is not a class here, and the parameter is expected as int. This fixes a documentation bug I introduced in cd16a35 (gitpython-developers#1725).
Configuration menu - View commit details
-
Copy full SHA for 30f7da5 - Browse repository at this point
Copy the full SHA 30f7da5View commit details
Commits on Feb 29, 2024
-
- Fix long-outdated information in the git.objects.tag docstring that seems to have been left over from when there was no such separate module. This module has only a tag-related class, not all classes that derive from git.object.base.Object. - Expand the git.objects.tag docstring to clarify what the module provides, add a git.refs.tag module docstring explaining what that provides, and cross-reference them with an explanation of how they differ (mentioning how this relates to git concepts). - Expand thie git.object.tag.TagObject class docstring to include the term "annotated" (retaining "non-lightweight" in parentheses).
Configuration menu - View commit details
-
Copy full SHA for 6126997 - Browse repository at this point
Copy the full SHA 6126997View commit details -
Fix param name in TagRefernece docstring and add info
The "reference" parameter was listed as "ref" in the docstring. This fixes that, slightly expands its description, and also adds documentation for the "repo" parameter.
Configuration menu - View commit details
-
Copy full SHA for 110706e - Browse repository at this point
Copy the full SHA 110706eView commit details -
Undo some expansion of "reference" parameter
This keeps most of the changes from the previous commit, but it undoes the expansion of the git object types a lightweight tag can refer to into GitPython git.objects.base.Object-based types, which seems more misleading than helpful because an uncareful reading could lead to an incorrect belief that the corresponding argument should or could be an object of such types.
Configuration menu - View commit details
-
Copy full SHA for b0e5bff - Browse repository at this point
Copy the full SHA b0e5bffView commit details -
Configuration menu - View commit details
-
Copy full SHA for a5a1b2c - Browse repository at this point
Copy the full SHA a5a1b2cView commit details -
Configuration menu - View commit details
-
Copy full SHA for 018ebaf - Browse repository at this point
Copy the full SHA 018ebafView commit details -
Better explain conditional cleanup in test_base_object
This expands the comment added in 41fac85 (gitpython-developers#1770) to make more clear that this particular cleanup is deliberately done only when the operation was successful (and why).
Configuration menu - View commit details
-
Copy full SHA for 608147e - Browse repository at this point
Copy the full SHA 608147eView commit details -
Revise test suite docstrings and comments
In a more limited way than in the git/ code. Docstring revisions are, in spirit, along the same lines as those in the git package, but much more conservative, because the tests' docstrings are not rendered into Sphinx documentation and there is no current plan to do so (so the tradeoffs are different, with even a tiny decrease in clarity when read in the code being a reason to avoid changes that use Sphinx roles more robustly or that would improve hypothetical rendered documentation), and because the test suite uses docstrings more sparingly and the existing docstrings were mostly already clear and easy to read. This wraps commnts to 88 columns as most comments now are in the git package, except it avoids doing so when doing so would make anything even slightly less clear, and where it would require significant further style or spacing changes for it to remain obvious (even before reading a comment) what the comment applies to, and in most portions of tutorial-generating test case code (where, although clarity would improve when reading the tests, it might sometimes decrease in the generated documentation).
Configuration menu - View commit details
-
Copy full SHA for 5cf5b60 - Browse repository at this point
Copy the full SHA 5cf5b60View commit details -
Better clarify Submodule.branch_path documentation
This revisits the changes in 3813bfb and takes a different approach, using the phrase "full repository-relative path" that is used elsewhere in the documentation and seems clear in context. Although this brings back the potential confusion around having the terms "full" and "relative" used together to describe a path, this may no longer be an issue now that the phrase "repository-relative" is used here as it is elsewhere. (In particular, see the SymbolicReference.to_full_path docstring.)
Configuration menu - View commit details
-
Copy full SHA for 4b04d8a - Browse repository at this point
Copy the full SHA 4b04d8aView commit details -
Configuration menu - View commit details
-
Copy full SHA for 254c82a - Browse repository at this point
Copy the full SHA 254c82aView commit details -
Fix exception type in require_remote_ref_path docstring
The require_remote_ref_path decorator has always used ValueError (ever since its introduction in a92ab80) but was documented as using TypeError. ValueError is the correct exception to raise here, since this is not any kind of type error or related condition. So the bug wasn't in the function's behavior, but instead in the way that behavior was documented. (The bug was fairly minor, since the function is not listed in __all__.)
Configuration menu - View commit details
-
Copy full SHA for 679d2e8 - Browse repository at this point
Copy the full SHA 679d2e8View commit details -
Configuration menu - View commit details
-
Copy full SHA for ee0301a - Browse repository at this point
Copy the full SHA ee0301aView commit details -
Configuration menu - View commit details
-
Copy full SHA for 231c3ef - Browse repository at this point
Copy the full SHA 231c3efView commit details -
Configuration menu - View commit details
-
Copy full SHA for e166a0a - Browse repository at this point
Copy the full SHA e166a0aView commit details -
Configuration menu - View commit details
-
Copy full SHA for ffeb7e7 - Browse repository at this point
Copy the full SHA ffeb7e7View commit details -
Configuration menu - View commit details
-
Copy full SHA for ec93955 - Browse repository at this point
Copy the full SHA ec93955View commit details -
Configuration menu - View commit details
-
Copy full SHA for 63983c2 - Browse repository at this point
Copy the full SHA 63983c2View commit details -
Somewhat improve _get_ref_info{,_helper} docstrings
+ Add a missing :class: reference in _get_commit docstring.
Configuration menu - View commit details
-
Copy full SHA for f43292e - Browse repository at this point
Copy the full SHA f43292eView commit details -
A couple more small docstring refinements
- Single vs. double backtick error/inconsistency in one place (parameter names were in in doubled backticks, now single) - Undo making "Iterator" in the phrase "Iterator yielding" a reference to collections.abc.Iterator, which is unnecessary and not done anywhere else.
Configuration menu - View commit details
-
Copy full SHA for 37c93de - Browse repository at this point
Copy the full SHA 37c93deView commit details