docs: render links taking alias into account (#433)

Author: pavelfeldman

playwright/async_api/_generated.py

@@ -693,7 +693,7 @@ async def wait_for_event(
     ) -> typing.Any:
         """WebSocket.wait_for_event
 
-        > NOTE: In most cases, you should use `web_socket.wait_for_event()`.
+        > NOTE: In most cases, you should use `web_socket.expect_event()`.
 
         Waits for given `event` to fire. If predicate is provided, it passes event's value into the `predicate` function and
         waits for `predicate(event)` to return a truthy value. Will throw an error if the socket is closed before the `event` is
@@ -5494,7 +5494,7 @@ def set_default_navigation_timeout(self, timeout: float) -> NoneType:
         - `page.goto()`
         - `page.reload()`
         - `page.set_content()`
-        - `page.wait_for_navigation()`
+        - `page.expect_navigation()`
 
         > NOTE: `page.set_default_navigation_timeout()` takes priority over `page.set_default_timeout()`,
         `browser_context.set_default_timeout()` and `browser_context.set_default_navigation_timeout()`.
@@ -5548,7 +5548,7 @@ async def query_selector(
         The method finds an element matching the specified selector within the page. If no elements match the selector, the
         return value resolves to `null`.
 
-        Shortcut for main frame's `frame.$()`.
+        Shortcut for main frame's `frame.query_selector()`.
 
         Parameters
         ----------
@@ -5577,7 +5577,7 @@ async def query_selector_all(self, selector: str) -> typing.List["ElementHandle"
         The method finds all elements matching the specified selector within the page. If no elements match the selector, the
         return value resolves to `[]`.
 
-        Shortcut for main frame's `frame.$$()`.
+        Shortcut for main frame's `frame.query_selector_all()`.
 
         Parameters
         ----------
@@ -6065,7 +6065,7 @@ async def eval_on_selector(
         The method finds an element matching the specified selector within the page and passes it as a first argument to
         `pageFunction`. If no elements match the selector, the method throws an error. Returns the value of `pageFunction`.
 
-        If `pageFunction` returns a [Promise], then `page.$eval()` would wait for the promise to resolve and return its
+        If `pageFunction` returns a [Promise], then `page.eval_on_selector()` would wait for the promise to resolve and return its
         value.
 
         Examples:
@@ -6076,7 +6076,7 @@ async def eval_on_selector(
         html = await page.eval_on_selector(\".main-container\", \"(e, suffix) => e.outer_html + suffix\", \"hello\")
         ```
 
-        Shortcut for main frame's `frame.$eval()`.
+        Shortcut for main frame's `frame.eval_on_selector()`.
 
         Parameters
         ----------
@@ -6124,7 +6124,7 @@ async def eval_on_selector_all(
         The method finds all elements matching the specified selector within the page and passes an array of matched elements as
         a first argument to `pageFunction`. Returns the result of `pageFunction` invocation.
 
-        If `pageFunction` returns a [Promise], then `page.$$eval()` would wait for the promise to resolve and return its
+        If `pageFunction` returns a [Promise], then `page.eval_on_selector_all()` would wait for the promise to resolve and return its
         value.
 
         Examples:
@@ -6649,7 +6649,7 @@ async def wait_for_event(
     ) -> typing.Any:
         """Page.wait_for_event
 
-        > NOTE: In most cases, you should use `page.wait_for_event()`.
+        > NOTE: In most cases, you should use `page.expect_event()`.
 
         Waits for given `event` to fire. If predicate is provided, it passes event's value into the `predicate` function and
         waits for `predicate(event)` to return a truthy value. Will throw an error if the socket is closed before the `event` is
@@ -7100,7 +7100,7 @@ async def close(self, run_before_unload: bool = None) -> NoneType:
         By default, `page.close()` **does not** run `beforeunload` handlers.
 
         > NOTE: if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned and should be handled manually
-        via [`event: Page.dialog`] event.
+        via `page.on('dialog')` event.
 
         Parameters
         ----------
@@ -8396,7 +8396,7 @@ def expect_navigation(
         > NOTE: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is
         considered a navigation.
 
-        Shortcut for main frame's `frame.wait_for_navigation()`.
+        Shortcut for main frame's `frame.expect_navigation()`.
 
         Parameters
         ----------
@@ -8602,7 +8602,7 @@ def set_default_navigation_timeout(self, timeout: float) -> NoneType:
         - `page.goto()`
         - `page.reload()`
         - `page.set_content()`
-        - `page.wait_for_navigation()`
+        - `page.expect_navigation()`
 
         > NOTE: `page.set_default_navigation_timeout()` and `page.set_default_timeout()` take priority over
         `browser_context.set_default_navigation_timeout()`.
@@ -9251,7 +9251,7 @@ async def wait_for_event(
     ) -> typing.Any:
         """BrowserContext.wait_for_event
 
-        > NOTE: In most cases, you should use `browser_context.wait_for_event()`.
+        > NOTE: In most cases, you should use `browser_context.expect_event()`.
 
         Waits for given `event` to fire. If predicate is provided, it passes event's value into the `predicate` function and
         waits for `predicate(event)` to return a truthy value. Will throw an error if the socket is closed before the `event` is

playwright/sync_api/_generated.py

@@ -697,7 +697,7 @@ def wait_for_event(
     ) -> typing.Any:
         """WebSocket.wait_for_event
 
-        > NOTE: In most cases, you should use `web_socket.wait_for_event()`.
+        > NOTE: In most cases, you should use `web_socket.expect_event()`.
 
         Waits for given `event` to fire. If predicate is provided, it passes event's value into the `predicate` function and
         waits for `predicate(event)` to return a truthy value. Will throw an error if the socket is closed before the `event` is
@@ -5629,7 +5629,7 @@ def set_default_navigation_timeout(self, timeout: float) -> NoneType:
         - `page.goto()`
         - `page.reload()`
         - `page.set_content()`
-        - `page.wait_for_navigation()`
+        - `page.expect_navigation()`
 
         > NOTE: `page.set_default_navigation_timeout()` takes priority over `page.set_default_timeout()`,
         `browser_context.set_default_timeout()` and `browser_context.set_default_navigation_timeout()`.
@@ -5681,7 +5681,7 @@ def query_selector(self, selector: str) -> typing.Union["ElementHandle", NoneTyp
         The method finds an element matching the specified selector within the page. If no elements match the selector, the
         return value resolves to `null`.
 
-        Shortcut for main frame's `frame.$()`.
+        Shortcut for main frame's `frame.query_selector()`.
 
         Parameters
         ----------
@@ -5710,7 +5710,7 @@ def query_selector_all(self, selector: str) -> typing.List["ElementHandle"]:
         The method finds all elements matching the specified selector within the page. If no elements match the selector, the
         return value resolves to `[]`.
 
-        Shortcut for main frame's `frame.$$()`.
+        Shortcut for main frame's `frame.query_selector_all()`.
 
         Parameters
         ----------
@@ -6212,7 +6212,7 @@ def eval_on_selector(
         The method finds an element matching the specified selector within the page and passes it as a first argument to
         `pageFunction`. If no elements match the selector, the method throws an error. Returns the value of `pageFunction`.
 
-        If `pageFunction` returns a [Promise], then `page.$eval()` would wait for the promise to resolve and return its
+        If `pageFunction` returns a [Promise], then `page.eval_on_selector()` would wait for the promise to resolve and return its
         value.
 
         Examples:
@@ -6223,7 +6223,7 @@ def eval_on_selector(
         html = page.eval_on_selector(\".main-container\", \"(e, suffix) => e.outer_html + suffix\", \"hello\")
         ```
 
-        Shortcut for main frame's `frame.$eval()`.
+        Shortcut for main frame's `frame.eval_on_selector()`.
 
         Parameters
         ----------
@@ -6273,7 +6273,7 @@ def eval_on_selector_all(
         The method finds all elements matching the specified selector within the page and passes an array of matched elements as
         a first argument to `pageFunction`. Returns the result of `pageFunction` invocation.
 
-        If `pageFunction` returns a [Promise], then `page.$$eval()` would wait for the promise to resolve and return its
+        If `pageFunction` returns a [Promise], then `page.eval_on_selector_all()` would wait for the promise to resolve and return its
         value.
 
         Examples:
@@ -6810,7 +6810,7 @@ def wait_for_event(
     ) -> typing.Any:
         """Page.wait_for_event
 
-        > NOTE: In most cases, you should use `page.wait_for_event()`.
+        > NOTE: In most cases, you should use `page.expect_event()`.
 
         Waits for given `event` to fire. If predicate is provided, it passes event's value into the `predicate` function and
         waits for `predicate(event)` to return a truthy value. Will throw an error if the socket is closed before the `event` is
@@ -7274,7 +7274,7 @@ def close(self, run_before_unload: bool = None) -> NoneType:
         By default, `page.close()` **does not** run `beforeunload` handlers.
 
         > NOTE: if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned and should be handled manually
-        via [`event: Page.dialog`] event.
+        via `page.on('dialog')` event.
 
         Parameters
         ----------
@@ -8601,7 +8601,7 @@ def expect_navigation(
         > NOTE: Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is
         considered a navigation.
 
-        Shortcut for main frame's `frame.wait_for_navigation()`.
+        Shortcut for main frame's `frame.expect_navigation()`.
 
         Parameters
         ----------
@@ -8807,7 +8807,7 @@ def set_default_navigation_timeout(self, timeout: float) -> NoneType:
         - `page.goto()`
         - `page.reload()`
         - `page.set_content()`
-        - `page.wait_for_navigation()`
+        - `page.expect_navigation()`
 
         > NOTE: `page.set_default_navigation_timeout()` and `page.set_default_timeout()` take priority over
         `browser_context.set_default_navigation_timeout()`.
@@ -9470,7 +9470,7 @@ def wait_for_event(
     ) -> typing.Any:
         """BrowserContext.wait_for_event
 
-        > NOTE: In most cases, you should use `browser_context.wait_for_event()`.
+        > NOTE: In most cases, you should use `browser_context.expect_event()`.
 
         Waits for given `event` to fire. If predicate is provided, it passes event's value into the `predicate` function and
         waits for `predicate(event)` to return a truthy value. Will throw an error if the socket is closed before the `event` is

scripts/documentation_provider.py

@@ -37,6 +37,7 @@ class DocumentationProvider:
     def __init__(self, is_async: bool) -> None:
         self.is_async = is_async
         self.api: Any = {}
+        self.links: Dict[str, str] = {}
         self.printed_entries: List[str] = []
         process_output = subprocess.run(
             ["python", "-m", "playwright", "print-api-json"],
@@ -53,19 +54,23 @@ def _patch_case(self) -> None:
             members = {}
             self.classes[clazz["name"]] = clazz
             for member in clazz["members"]:
-                if member["kind"] == "event":
-                    continue
-                method_name = member["name"]
-                new_name = to_snake_case(method_name)
+                member_name = member["name"]
                 alias = (
                     member["langs"].get("aliases").get("python")
                     if member["langs"].get("aliases")
                     else None
                 )
+                new_name = member_name
                 if alias:
                     new_name = alias
-                members[new_name] = member
+                self._add_link(member["kind"], clazz["name"], member_name, new_name)
+
+                if member["kind"] == "event":
+                    continue
+
+                new_name = to_snake_case(new_name)
                 member["name"] = new_name
+                members[new_name] = member
                 if member["langs"].get("types") and member["langs"]["types"].get(
                     "python"
                 ):
@@ -90,6 +95,21 @@ def _patch_case(self) -> None:
 
             clazz["members"] = members
 
+    def _add_link(self, kind: str, clazz: str, member: str, alias: str) -> None:
+        match = re.match(r"(JS|CDP|[A-Z])([^.]+)", clazz)
+        if not match:
+            raise Exception("Invalid class " + clazz)
+        var_name = to_snake_case(f"{match.group(1).lower()}{match.group(2)}")
+        new_name = to_snake_case(alias)
+        if kind == "event":
+            self.links[
+                f"[`event: {clazz}.{member}`]"
+            ] = f"`{var_name}.on('{new_name}')`"
+        elif kind == "property":
+            self.links[f"[`property: {clazz}.{member}`]"] = f"`{var_name}.{new_name}`"
+        else:
+            self.links[f"[`method: {clazz}.{member}`]"] = f"`{var_name}.{new_name}()`"
+
     def print_entry(
         self,
         class_name: str,
@@ -223,21 +243,8 @@ def beautify_method_comment(self, comment: str, indent: str) -> str:
         return self.indent_paragraph("\n".join(result), indent)
 
     def render_links(self, comment: str) -> str:
-        def render(match: Any) -> str:
-            return f"{to_snake_case(match.group(1).lower() + match.group(2))}.{to_snake_case(match.group(3))}"
-
-        def render_property(match: Any) -> str:
-            return f"`{render(match)}`"
-
-        def render_method(match: Any) -> str:
-            return f"`{render(match)}()`"
-
-        comment = re.sub(
-            r"\[`method: (JS|CDP|[A-Z])([^.]+)\.([^`]+)`\]", render_method, comment
-        )
-        comment = re.sub(
-            r"\[`property: (JS|CDP|[A-Z])([^.]+)\.([^`]+)`\]", render_property, comment
-        )
+        for [old, new] in self.links.items():
+            comment = comment.replace(old, new)
         return comment
 
     def make_optional(self, text: str) -> str: