Merge pull request #1855 from EliahKagan/reference

Expand what is included in the API Reference

doc/source/reference.rst

@@ -3,37 +3,40 @@
 API Reference
 =============
 
-Version
--------
+Top-Level
+---------
 
 .. py:data:: git.__version__
 
    Current GitPython version.
 
+.. automodule:: git
+   :members: refresh
+
 Objects.Base
 ------------
 
 .. automodule:: git.objects.base
    :members:
    :undoc-members:
    :special-members:
- 
+
 Objects.Blob
 ------------
 
 .. automodule:: git.objects.blob
    :members:
    :undoc-members:
    :special-members:
-   
+
 Objects.Commit
 --------------
 
 .. automodule:: git.objects.commit
    :members:
    :undoc-members:
    :special-members:
-   
+
 Objects.Tag
 -----------
 
@@ -73,15 +76,15 @@ Objects.Submodule.root
    :members:
    :undoc-members:
    :special-members:
-   
+
 Objects.Submodule.util
 ----------------------
 
 .. automodule:: git.objects.submodule.util
    :members:
    :undoc-members:
    :special-members:
-   
+
 Objects.Util
 -------------
 
@@ -105,23 +108,23 @@ Index.Functions
    :members:
    :undoc-members:
    :special-members:
-   
+
 Index.Types
 -----------
 
 .. automodule:: git.index.typ
    :members:
    :undoc-members:
    :special-members:
-   
+
 Index.Util
 -------------
 
 .. automodule:: git.index.util
    :members:
    :undoc-members:
    :special-members:
-   
+
 GitCmd
 ------
 
@@ -137,7 +140,7 @@ Config
    :members:
    :undoc-members:
    :special-members:
-   
+
 Diff
 ----
 
@@ -154,15 +157,15 @@ Exceptions
    :undoc-members:
    :special-members:
 
- 
+
 Refs.symbolic
 -------------
 
 .. automodule:: git.refs.symbolic
    :members:
    :undoc-members:
    :special-members:
-   
+
 Refs.reference
 --------------
 
@@ -178,31 +181,31 @@ Refs.head
    :members:
    :undoc-members:
    :special-members:
-   
+
 Refs.tag
 ------------
 
 .. automodule:: git.refs.tag
    :members:
    :undoc-members:
    :special-members:
-   
+
 Refs.remote
 ------------
 
 .. automodule:: git.refs.remote
    :members:
    :undoc-members:
    :special-members:
-   
+
 Refs.log
 ------------
 
 .. automodule:: git.refs.log
    :members:
    :undoc-members:
    :special-members:
-   
+
 Remote
 ------
 
@@ -218,7 +221,7 @@ Repo.Base
    :members:
    :undoc-members:
    :special-members:
-   
+
 Repo.Functions
 --------------
 
@@ -227,6 +230,30 @@ Repo.Functions
    :undoc-members:
    :special-members:
 
+Compat
+------
+
+.. automodule:: git.compat
+   :members:
+   :undoc-members:
+   :special-members:
+
+DB
+--
+
+.. automodule:: git.db
+   :members:
+   :undoc-members:
+   :special-members:
+
+Types
+-----
+
+.. automodule:: git.types
+   :members:
+   :undoc-members:
+   :special-members:
+
 Util
 ----
 

git/cmd.py

@@ -389,7 +389,9 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
 
     @classmethod
     def refresh(cls, path: Union[None, PathLike] = None) -> bool:
-        """This gets called by the refresh function (see the top level ``__init__``).
+        """Update information about the git executable :class:`Git` objects will use.
+
+        Called by the :func:`git.refresh` function in the top level ``__init__``.
 
         :param path:
             Optional path to the git executable. If not absolute, it is resolved
@@ -1486,7 +1488,9 @@ def _call_process(
     def _parse_object_header(self, header_line: str) -> Tuple[str, str, int]:
         """
         :param header_line:
-            <hex_sha> type_string size_as_int
+            A line of the form::
+
+                <hex_sha> type_string size_as_int
 
         :return:
             (hex_sha, type_string, size_as_int)
@@ -1576,7 +1580,7 @@ def get_object_data(self, ref: str) -> Tuple[str, str, int, bytes]:
         return (hexsha, typename, size, data)
 
     def stream_object_data(self, ref: str) -> Tuple[str, str, int, "Git.CatFileContentStream"]:
-        """Similar to :meth:`get_object_header`, but returns the data as a stream.
+        """Similar to :meth:`get_object_data`, but returns the data as a stream.
 
         :return:
             (hexsha, type_string, size_as_int, stream)

git/compat.py

@@ -61,7 +61,7 @@
 
 :note:
     For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while
-    ``sys.platform == "darwin"`.
+    ``sys.platform == "darwin"``.
 """
 
 defenc = sys.getfilesystemencoding()

git/db.py

@@ -38,11 +38,12 @@ def __init__(self, root_path: PathLike, git: "Git") -> None:
         self._git = git
 
     def info(self, binsha: bytes) -> OInfo:
+        """Get a git object header (using git itself)."""
         hexsha, typename, size = self._git.get_object_header(bin_to_hex(binsha))
         return OInfo(hex_to_bin(hexsha), typename, size)
 
     def stream(self, binsha: bytes) -> OStream:
-        """For now, all lookup is done by git itself"""
+        """Get git object data as a stream supporting ``read()`` (using git itself)."""
         hexsha, typename, size, stream = self._git.stream_object_data(bin_to_hex(binsha))
         return OStream(hex_to_bin(hexsha), typename, size, stream)
 

git/remote.py

@@ -338,7 +338,11 @@ class FetchInfo(IterableObj):
 
     @classmethod
     def refresh(cls) -> Literal[True]:
-        """This gets called by the refresh function (see the top level ``__init__``)."""
+        """Update information about which ``git fetch`` flags are supported by the git
+        executable being used.
+
+        Called by the :func:`git.refresh` function in the top level ``__init__``.
+        """
         # Clear the old values in _flag_map.
         with contextlib.suppress(KeyError):
             del cls._flag_map["t"]