Pydoctor fixes (#1576)

.github/workflows/docs.yml

@@ -1,15 +1,15 @@
-
+---
 name: API Docs
 
-on:
+"on":
   push:
-    branches: [ main, master ]
+    branches: [main, master]
   pull_request:
   schedule:
-    - cron: "0 6 * * *" # Daily 6AM UTC build
+    - cron: "0 6 * * *"  # Daily 6AM UTC build
 
 jobs:
-  test:
+  apidocs:
     runs-on: ubuntu-latest
 
     steps:
@@ -17,10 +17,9 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.13"
       - name: Install pydoctor
         run: |
-          sudo apt-get update && sudo apt -y install -y pydoctor python3-pip
           pip3 install pydoctor
       - name: Generate docs
         run: make apidocs

dulwich/client.py

@@ -2918,6 +2918,8 @@ def get_transport_and_path_from_url(
       url: URL to open (a unicode string)
       config: Optional config object
       operation: Kind of operation that'll be performed; "pull" or "push"
+
+    Keyword Args:
       thin_packs: Whether or not thin packs should be retrieved
       report_activity: Optional callback for reporting transport
         activity.
@@ -2987,6 +2989,8 @@ def get_transport_and_path(
       location: URL or path (a string)
       config: Optional config object
       operation: Kind of operation that'll be performed; "pull" or "push"
+
+    Keyword Args:
       thin_packs: Whether or not thin packs should be retrieved
       report_activity: Optional callback for reporting transport
         activity.

dulwich/ignore.py

@@ -185,7 +185,7 @@ def _handle_double_asterisk(segments: list[bytes], i: int) -> tuple[bytes, bool]
 
 
 def _handle_leading_patterns(pat: bytes, res: bytes) -> tuple[bytes, bytes]:
-    """Handle leading patterns like /**/, **/, or /."""
+    """Handle leading patterns like ``/**/``, ``**/``, or ``/``."""
     if pat.startswith(b"/**/"):
         # Leading /** is same as **
         return pat[4:], b"(.*/)?"

dulwich/index.py

@@ -1153,7 +1153,7 @@ def build_file_from_blob(
       target_path: Path to write to
       honor_filemode: An optional flag to honor core.filemode setting in
         config file, default is core.filemode=True, change executable bit
-      symlink: Function to use for creating symlinks
+      symlink_fn: Function to use for creating symlinks
     Returns: stat object for the file
     """
     try:

dulwich/object_store.py

@@ -403,7 +403,6 @@ class PackBasedObjectStore(BaseObjectStore):
 
         Args:
           count: Number of items to add
-          pack_data: Iterator over pack data tuples
         """
         if count == 0:
             # Don't bother writing an empty pack file
@@ -1273,7 +1272,6 @@ class MemoryObjectStore(BaseObjectStore):
 
         Args:
           count: Number of items to add
-          pack_data: Iterator over pack data tuples
         """
         for unpacked_object in unpacked_objects:
             self.add_object(unpacked_object.sha_file())
@@ -1398,7 +1396,6 @@ class MissingObjectFinder:
       get_tagged: Function that returns a dict of pointed-to sha -> tag
         sha for including tags.
       get_parents: Optional function for getting the parents of a commit.
-      tagged: dict of pointed-to sha -> tag sha for including tags
     """
 
     def __init__(

dulwich/pack.py

@@ -1841,8 +1841,6 @@ def write_pack(
 
     Args:
       filename: Path to the new pack file (without .pack extension)
-      container: PackedObjectContainer
-      entries: Sequence of (object_id, path) tuples to write
       delta_window_size: Delta window size
       deltify: Whether to deltify pack objects
       compression_level: the zlib compression level
@@ -2051,8 +2049,6 @@ def generate_unpacked_objects(
 ) -> Iterator[UnpackedObject]:
     """Create pack data from objects.
 
-    Args:
-      objects: Pack objects
     Returns: Tuples with (type_num, hexdigest, delta base, object chunks)
     """
     todo = dict(object_ids)
@@ -2105,7 +2101,6 @@ def write_pack_from_container(
     Args:
       write: write function to use
       container: PackedObjectContainer
-      entries: Sequence of (object_id, path) tuples to write
       delta_window_size: Sliding window size for searching for deltas;
                          Set to None for default window size.
       deltify: Whether to deltify objects

dulwich/porcelain.py

@@ -524,13 +524,16 @@ def clone(
       branch: Optional branch or tag to be used as HEAD in the new repository
         instead of the cloned repository's HEAD.
       config: Configuration to use
-      refspecs: refspecs to fetch. Can be a bytestring, a string, or a list of
-        bytestring/string.
       filter_spec: A git-rev-list-style object filter spec, as an ASCII string.
         Only used if the server supports the Git protocol-v2 'filter'
         feature, and ignored otherwise.
       protocol_version: desired Git protocol version. By default the highest
         mutually supported protocol version will be used.
+
+    Keyword Args:
+      refspecs: refspecs to fetch. Can be a bytestring, a string, or a list of
+        bytestring/string.
+
     Returns: The new repository
     """
     if outstream is not None:
@@ -1846,8 +1849,7 @@ def for_each_ref(
     Args:
       repo: Path to the repository
       pattern: Optional glob (7) patterns to filter the refs with
-    Returns:
-      List of bytes tuples with: (sha, object_type, ref_name)
+    Returns: List of bytes tuples with: (sha, object_type, ref_name)
     """
     if isinstance(pattern, str):
         pattern = os.fsencode(pattern)

dulwich/protocol.py

@@ -201,7 +201,7 @@ def filter_ref_prefix(refs, prefixes):
 
     Args:
       refs: A list of refs.
-      prefix: The prefix to filter by.
+      prefixes: The prefixes to filter by.
     """
     return {k: v for k, v in refs.items() if any(k.startswith(p) for p in prefixes)}
 

dulwich/repo.py

@@ -797,6 +797,8 @@ class BaseRepo:
         Args:
           include: Iterable of SHAs of commits to include along with their
             ancestors. Defaults to [HEAD]
+
+        Keyword Args:
           exclude: Iterable of SHAs of commits to exclude along with their
             ancestors, overriding includes.
           order: ORDER_* constant specifying the order of results.
@@ -815,6 +817,7 @@ class BaseRepo:
           queue_cls: A class to use for a queue of commits, supporting the
             iterator protocol. The constructor takes a single argument, the
             Walker.
+
         Returns: A `Walker` object
         """
         from .walk import Walker