docs: render supported subclass interface docstrings (#1848)

Sphinx omits underscore-prefixed methods by default, hiding documented
extension points such as `RemoteProgress._parse_progress_line()` and
`LockFile._obtain_lock()`. Traversal documentation used a separate allowlist,
and `Tree.traverse()` linked to its implementation using an ordinary URL.

Mark supported subclass interfaces with Sphinx's built-in `:meta public:`
docstring metadata. Remove the traversal-specific `:private-members:` list,
use a method reference for traversal documentation, and explain this
convention in `CONTRIBUTING.md`. Private implementation helpers stay hidden.
Repair an existing malformed `is_relative_url()` return field so strict
HTML validation can complete.

Before this change, the HTML reference lacked the progress and lock
extension-point targets. The strict Sphinx HTML build now passes. Assertions
against its output verify all five selected interface targets, the traversal
link, and omission of `LockFile._lock_file_path()`. Runtime logic is unchanged.

Author: codex

CONTRIBUTING.md

@@ -48,6 +48,12 @@ Attributing AI assistance in commit metadata, for example with a `Co-authored-by
 trailer, is welcome but not required. Code is reviewed the same way regardless of its
 origin.
 
+## Documenting subclass interfaces
+
+Use Sphinx's `:meta public:` field in docstrings of underscore-prefixed methods
+that form a supported interface for subclasses. This includes their documentation
+in the API reference without exposing unrelated private implementation details.
+
 ## Temporary test directories
 
 Tests require Python 3.11+, Git 2.52+, Bash, and the `test` extra, which installs

doc/source/reference.rst

@@ -91,7 +91,6 @@ Objects.Util
 .. automodule:: git.objects.util
    :members:
    :undoc-members:
-   :private-members: _get_intermediate_items, _list_traverse, _traverse
    :special-members:
 
 Index.Base

git/objects/submodule/util.py

@@ -99,8 +99,11 @@ def _find_last_dir_sep(url: str) -> int:
 
 
 def is_relative_url(url: str) -> bool:
-    """:return: ``True`` if `url` starts with ``./`` or ``../``, which git resolves
-    against the superproject's remote rather than treating as a path"""
+    """Check whether Git resolves a URL against the superproject's remote.
+
+    :return:
+        ``True`` if `url` starts with ``./`` or ``../``.
+    """
     return _starts_with_dot_slash(url) or _starts_with_dot_dot_slash(url)
 
 

git/objects/tree.py

@@ -328,8 +328,7 @@ def traverse(
         ignore_self: int = 1,
         as_edge: bool = False,
     ) -> Union[Iterator[IndexObjUnion], Iterator[TraversedTreeTup]]:
-        """For documentation, see
-        `Traversable._traverse() <git.objects.util.Traversable._traverse>`.
+        """For documentation, see :meth:`~git.objects.util.Traversable._traverse`.
 
         Trees are set to ``visit_once = False`` to gain more performance in the
         traversal.

git/objects/util.py

@@ -334,6 +334,8 @@ class Traversable(Protocol):
     @abstractmethod
     def _get_intermediate_items(cls, item: Any) -> Sequence["Traversable"]:
         """
+        :meta public:
+
         :return:
             Tuple of items connected to the given item.
             Must be implemented in subclass.
@@ -354,6 +356,8 @@ def _list_traverse(
     ) -> IterableList[Union["Commit", "Submodule", "Tree", "Blob"]]:
         """Traverse self and collect all items found.
 
+        :meta public:
+
         :return:
             :class:`~git.util.IterableList` with the results of the traversal as
             produced by :meth:`traverse`::
@@ -401,6 +405,8 @@ def _traverse(
     ) -> Union[Iterator[Union["Traversable", "Blob"]], Iterator[TraversedTup]]:
         """Iterator yielding items found when traversing `self`.
 
+        :meta public:
+
         :param predicate:
             A function ``f(i,d)`` that returns ``False`` if item i at depth ``d`` should
             not be included in the result.

git/util.py

@@ -712,6 +712,8 @@ def _parse_progress_line(self, line: AnyStr) -> Optional[object]:
         """Parse progress information from the given line as retrieved by
         :manpage:`git-push(1)` or :manpage:`git-fetch(1)`.
 
+        :meta public:
+
         - Lines that do not contain progress info are stored in :attr:`other_lines`.
         - Lines that seem to contain an error (i.e. start with ``error:`` or ``fatal:``)
           are stored in :attr:`error_lines`.
@@ -1171,6 +1173,8 @@ def _obtain_lock_or_raise(self) -> None:
     def _obtain_lock(self) -> None:
         """The default implementation will raise if a lock cannot be obtained.
 
+        :meta public:
+
         Subclasses may override this method to provide a different implementation.
         """
         return self._obtain_lock_or_raise()