[doc][api] add a function to check if an api is really public + bug f…

…ix for autosummary parser (#46261)

- Add a function to check if an api name is prefixed with `_`
- Also a function to check if an api is really public
- Fix a bug in autosummary parser

Test:
- CI

---------

Signed-off-by: can <[email protected]>

ci/ray_ci/doc/api.py

@@ -118,3 +118,23 @@ def get_canonical_name(self) -> str:
             attribute = getattr(attribute, token)
 
         return f"{attribute.__module__}.{attribute.__qualname__}"
+
+    def _is_private_name(self) -> bool:
+        """
+        Check if this API has a private name. Private names are those that start with
+        underscores.
+        """
+        name_has_underscore = self.name.split(".")[-1].startswith("_")
+        is_internal = ".internal." in self.name
+
+        return name_has_underscore or is_internal
+
+    def is_public(self) -> bool:
+        """
+        Check if this API is public. Public APIs are those that are annotated as public
+        and not have private names.
+        """
+        return (
+            self.annotation_type == AnnotationType.PUBLIC_API
+            and not self._is_private_name()
+        )

ci/ray_ci/doc/autodoc.py

@@ -97,8 +97,6 @@ def _parse_autodoc_rst(self, rst_file: str) -> List[API]:
         with open(rst_file, "r") as f:
             line = f.readline()
             while line:
-                line = line.strip()
-
                 # parse currentmodule block
                 if line.startswith(_SPHINX_CURRENTMODULE_HEADER):
                     module = line[len(_SPHINX_CURRENTMODULE_HEADER) :].strip()

ci/ray_ci/doc/test_api.py

@@ -113,5 +113,54 @@ def test_get_canonical_name():
     )
 
 
+def test_is_private_name():
+    test_data = [
+        {
+            "input": "a.b._private_function",
+            "output": True,
+        },
+        {
+            "input": "a.b.internal.public_function",
+            "output": True,
+        },
+        {
+            "input": "b.c.public_class",
+            "output": False,
+        },
+    ]
+    for test in test_data:
+        assert (
+            API(
+                name=test["input"],
+                annotation_type=AnnotationType.UNKNOWN,
+                code_type=CodeType.FUNCTION,
+            )._is_private_name()
+            == test["output"]
+        )
+
+
+def test_is_public():
+    assert not API(
+        name="a.b._private_function",
+        annotation_type=AnnotationType.PUBLIC_API,
+        code_type=CodeType.FUNCTION,
+    ).is_public()
+    assert not API(
+        name="a.b.internal.public_function",
+        annotation_type=AnnotationType.PUBLIC_API,
+        code_type=CodeType.FUNCTION,
+    ).is_public()
+    assert not API(
+        name="a.b.public_function",
+        annotation_type=AnnotationType.DEPRECATED,
+        code_type=CodeType.FUNCTION,
+    ).is_public()
+    assert API(
+        name="a.b.public_function",
+        annotation_type=AnnotationType.PUBLIC_API,
+        code_type=CodeType.FUNCTION,
+    ).is_public()
+
+
 if __name__ == "__main__":
     sys.exit(pytest.main(["-v", __file__]))

ci/ray_ci/doc/test_autodoc.py

@@ -16,7 +16,7 @@ def test_walk():
             f.write("\tapi_02.rst\n")
         with open(os.path.join(tmp, "api_01.rst"), "w") as f:
             f.write(".. currentmodule:: ci.ray_ci.doc\n")
-            f.write(".. autosummary::\n\n")
+            f.write(".. autosummary::\n")
             f.write("\t~mock.mock_function\n")
             f.write("\tmock.mock_module.mock_w00t\n")
         with open(os.path.join(tmp, "api_02.rst"), "w") as f: