Skip to content

Improve Sphinx role usage, including linking Git manpages #1879

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

Merged
merged 10 commits into from
Mar 16, 2024
Prev Previous commit
Next Next commit
Use :const: for constants that had the :attr: role
Note that this intentionally does *not* include some all-caps class
attributes that are not really constants:

- Git.GIT_PYTHON_GIT_EXECUTABLE is set by refresh functions,
  including on subsequent calls, which is an important and
  documented part of what those functions do. (Also, it is set
  automatically from an enviroment variable, which is not constant
  across runs; that it could not even in principle be replaced by a
  specific literal value is a further reason it is not a constant.)

- The Git.USE_SHELL attribute is a more ambiguous case. It is given
  a literal value (False) which it preferably remains. But setting
  it has been documented as something users can do (in the
  changelog, and later in regard to setting it being a deprecated
  operation).

The first of these is decisively not a constant even under a loose
definition, while the second is less clear. I've kept both with the
:attr: role.
  • Loading branch information
EliahKagan committed Mar 16, 2024
commit 85434571090a24ac84d1ce81f3fa74909e3d5c5f
2 changes: 1 addition & 1 deletion git/remote.py
Original file line number Diff line number Diff line change
Expand Up @@ -1177,7 +1177,7 @@ def push(
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.
:const:`PushInfo.ERROR` bit set in their flags.

If the operation fails completely, the length of the returned
:class:`PushInfoList` will be 0.
Expand Down
16 changes: 8 additions & 8 deletions git/util.py
Original file line number Diff line number Diff line change
Expand Up @@ -713,14 +713,14 @@ def update(
:param op_code:
Integer allowing to be compared against Operation IDs and stage IDs.

Stage IDs are :attr:`BEGIN` and :attr:`END`. :attr:`BEGIN` will only be set
once for each Operation ID as well as :attr:`END`. It may be that
:attr:`BEGIN` and :attr:`END` are set at once in case only one progress
message was emitted due to the speed of the operation. Between :attr:`BEGIN`
and :attr:`END`, none of these flags will be set.
Stage IDs are :const:`BEGIN` and :const:`END`. :const:`BEGIN` will only be
set once for each Operation ID as well as :const:`END`. It may be that
:const:`BEGIN` and :const:`END` are set at once in case only one progress
message was emitted due to the speed of the operation. Between
:const:`BEGIN` and :const:`END`, none of these flags will be set.

Operation IDs are all held within the :attr:`OP_MASK`. Only one Operation ID
will be active per call.
Operation IDs are all held within the :const:`OP_MASK`. Only one Operation
ID will be active per call.

:param cur_count:
Current absolute count of items.
Expand All @@ -730,7 +730,7 @@ def update(
maximum number of items or if it is (yet) unknown.

:param message:
In case of the :attr:`WRITING` operation, it contains the amount of bytes
In case of the :const:`WRITING` operation, it contains the amount of bytes
transferred. It may possibly be used for other purposes as well.

:note:
Expand Down