docstrings: only render async/sync dialect snippets (microsoft#426)

pavelfeldman · web-flow · commit 39374d005fc7 · 2021-01-13T18:14:07.000-08:00
diff --git a/playwright/async_api/_generated.py b/playwright/async_api/_generated.py
@@ -664,18 +664,12 @@ def expect_event(
         `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 fired.
 
-        ```python async
+        ```py
         async with ws.expect_event(event_name) as event_info:
             await ws.click("button")
         value = await event_info.value
         ```
 
-        ```python sync
-        with ws.expect_event(event_name) as event_info:
-            ws.click("button")
-        value = event_info.value
-        ```
-
         Parameters
         ----------
         event : str
@@ -4597,18 +4591,12 @@ def expect_navigation(
         cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`.
         Consider this example:
 
-        ```python async
+        ```py
         async with frame.expect_navigation():
             await frame.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
         # Context manager waited for the navigation to happen.
         ```
 
-        ```python sync
-        with frame.expect_navigation():
-            frame.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
-        # Context manager waited for the navigation to happen.
-        ```
-
         > 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.
 
@@ -7890,18 +7878,12 @@ def expect_event(
         `predicate` function and waits for `predicate(event)` to return a truthy value. Will throw an error if the page is
         closed before the `event` is fired.
 
-        ```python async
+        ```py
         async with page.expect_event(event_name) as event_info:
             await page.click("button")
         value = await event_info.value
         ```
 
-        ```python sync
-        with page.expect_event(event_name) as event_info:
-            page.click("button")
-        value = event_info.value
-        ```
-
         Parameters
         ----------
         event : str
@@ -8024,18 +8006,12 @@ def expect_navigation(
         cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`.
         Consider this example:
 
-        ```python async
+        ```py
         async with page.expect_navigation():
             await page.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
         # Context manager waited for the navigation to happen.
         ```
 
-        ```python sync
-        with page.expect_navigation():
-            page.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
-        # Context manager waited for the navigation to happen.
-        ```
-
         > 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.
 
@@ -8770,18 +8746,12 @@ def expect_event(
         `predicate` function and waits for `predicate(event)` to return a truthy value. Will throw an error if browser context
         is closed before the `event` is fired.
 
-        ```python async
+        ```py
         async with context.expect_event("page") as event_info:
             await context.click("button")
         page = await event_info.value
         ```
 
-        ```python sync
-        with context.expect_event("page") as event_info:
-            context.click("button")
-        page = event_info.value
-        ```
-
         Parameters
         ----------
         event : str
diff --git a/playwright/sync_api/_generated.py b/playwright/sync_api/_generated.py
@@ -670,13 +670,7 @@ def expect_event(
         `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 fired.
 
-        ```python async
-        async with ws.expect_event(event_name) as event_info:
-            await ws.click("button")
-        value = await event_info.value
-        ```
-
-        ```python sync
+        ```py
         with ws.expect_event(event_name) as event_info:
             ws.click("button")
         value = event_info.value
@@ -4720,13 +4714,7 @@ def expect_navigation(
         cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`.
         Consider this example:
 
-        ```python async
-        async with frame.expect_navigation():
-            await frame.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
-        # Context manager waited for the navigation to happen.
-        ```
-
-        ```python sync
+        ```py
         with frame.expect_navigation():
             frame.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
         # Context manager waited for the navigation to happen.
@@ -8117,13 +8105,7 @@ def expect_event(
         `predicate` function and waits for `predicate(event)` to return a truthy value. Will throw an error if the page is
         closed before the `event` is fired.
 
-        ```python async
-        async with page.expect_event(event_name) as event_info:
-            await page.click("button")
-        value = await event_info.value
-        ```
-
-        ```python sync
+        ```py
         with page.expect_event(event_name) as event_info:
             page.click("button")
         value = event_info.value
@@ -8247,13 +8229,7 @@ def expect_navigation(
         cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`.
         Consider this example:
 
-        ```python async
-        async with page.expect_navigation():
-            await page.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
-        # Context manager waited for the navigation to happen.
-        ```
-
-        ```python sync
+        ```py
         with page.expect_navigation():
             page.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
         # Context manager waited for the navigation to happen.
@@ -9008,13 +8984,7 @@ def expect_event(
         `predicate` function and waits for `predicate(event)` to return a truthy value. Will throw an error if browser context
         is closed before the `event` is fired.
 
-        ```python async
-        async with context.expect_event("page") as event_info:
-            await context.click("button")
-        page = await event_info.value
-        ```
-
-        ```python sync
+        ```py
         with context.expect_event("page") as event_info:
             context.click("button")
         page = event_info.value
diff --git a/scripts/documentation_provider.py b/scripts/documentation_provider.py
@@ -34,7 +34,8 @@
 
 
 class DocumentationProvider:
-    def __init__(self) -> None:
+    def __init__(self, is_async: bool) -> None:
+        self.is_async = is_async
         self.api: Any = {}
         self.printed_entries: List[str] = []
         process_output = subprocess.run(
@@ -190,21 +191,29 @@ def indent_paragraph(self, p: str, indent: str) -> str:
     def beautify_method_comment(self, comment: str, indent: str) -> str:
         lines = comment.split("\n")
         result = []
-        in_example = False
+        skip_example = False
         last_was_blank = True
         for line in lines:
             if not line.strip():
                 last_was_blank = True
                 continue
-            if line.strip() == "```js":
-                in_example = True
-            if not in_example:
+            match = re.match(r"\s*```(.+)", line)
+            if match:
+                lang = match[1]
+                if lang in ["html", "yml", "sh", "py", "python"]:
+                    skip_example = False
+                elif lang == "python " + ("async" if self.is_async else "sync"):
+                    skip_example = False
+                    line = "```py"
+                else:
+                    skip_example = True
+            if not skip_example:
                 if last_was_blank:
                     last_was_blank = False
                     result.append("")
                 result.append(self.render_links(line))
-            if line.strip() == "```":
-                in_example = False
+            if skip_example and line.strip() == "```":
+                skip_example = False
         return self.indent_paragraph("\n".join(result), indent)
 
     def render_links(self, comment: str) -> str:
diff --git a/scripts/generate_async_api.py b/scripts/generate_async_api.py
@@ -32,7 +32,7 @@
     signature,
 )
 
-documentation_provider = DocumentationProvider()
+documentation_provider = DocumentationProvider(True)
 
 
 def generate(t: Any) -> None:
diff --git a/scripts/generate_sync_api.py b/scripts/generate_sync_api.py
@@ -32,7 +32,7 @@
     signature,
 )
 
-documentation_provider = DocumentationProvider()
+documentation_provider = DocumentationProvider(False)
 
 
 def generate(t: Any) -> None:

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@`
`32`	`32`	`signature,`
`33`	`33`	`)`
`34`	`34`
`35`		`-documentation_provider = DocumentationProvider()`
	`35`	`+documentation_provider = DocumentationProvider(True)`
`36`	`36`
`37`	`37`
`38`	`38`	`def generate(t: Any) -> None:`