Add modified core docs to website, Partially flatten navbar (#238)

* docs: add core modules to mkdocs auto-generation

* docs: fix griffe warnings (mostly unnecessary type fields); minor rewrite of some docs

Author: Kajmany

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Docs: `core` modules included in documentation reference section. Slight modifications were done, mostly to remove warnings. @Kajmany
+
 ### Removed
 
 ## [0.15.2] - 2025-11-29

mkdocs.yml

@@ -22,6 +22,17 @@ nav:
           - Reading API responses: tutorials/api-responses.md
           - Playing with CDP: tutorials/cdp.md
   - Reference:
+      - core:
+          - browser: reference/core/browser.md
+          - cloudflare: reference/core/cloudflare.md
+          - config: reference/core/config.md
+          - connection: reference/core/connection.md
+          - element: reference/core/element.md
+          - expect: reference/core/expect.md
+          - intercept: reference/core/intercept.md
+          - keys: reference/core/keys.md
+          - tab: reference/core/tab.md
+          - util: reference/core/util.md
       - cdp:
           - accessibility: reference/cdp/accessibility.md
           - animation: reference/cdp/animation.md

scripts/mkdocs_generate_reference.py

@@ -30,7 +30,10 @@ def clean_reference_docs_dir() -> None:
 def get_documented_modules() -> list[Path]:
     return [
         path.relative_to(PACKAGE_ROOT)
-        for path in sorted(PACKAGE_ROOT.rglob("cdp/*.py"))
+        for path in (
+            sorted(PACKAGE_ROOT.rglob("core/*.py"))
+            + sorted(PACKAGE_ROOT.rglob("cdp/*.py"))
+        )
         if not path.stem.startswith("_")
     ]
 

zendriver/core/__init__.py

@@ -264,7 +264,7 @@ async def get(
         :param new_tab: open new tab
         :param new_window:  open new window
         :return: Page
-        :raises: asyncio.TimeoutError
+        :raises asyncio.TimeoutError:
         """
         if not self.connection:
             raise RuntimeError("Browser not yet started. use await browser.start()")
@@ -685,7 +685,6 @@ async def get_all(
         get all cookies
 
         :param requests_cookie_format: when True, returns python http.cookiejar.Cookie objects, compatible  with requests library and many others.
-        :type requests_cookie_format: bool
         :return:
         :rtype:
 
@@ -723,7 +722,6 @@ async def set_all(self, cookies: List[cdp.network.CookieParam]) -> None:
         set cookies
 
         :param cookies: list of cookies
-        :type cookies:
         :return:
         :rtype:
         """
@@ -745,7 +743,6 @@ async def save(self, file: PathLike = ".session.dat", pattern: str = ".*") -> No
         save all cookies (or a subset, controlled by `pattern`) to a file to be restored later
 
         :param file:
-        :type file:
         :param pattern: regex style pattern string.
                any cookie that has a  domain, key or value field which matches the pattern will be included.
                default = ".*"  (all)
@@ -754,7 +751,6 @@ async def save(self, file: PathLike = ".session.dat", pattern: str = ".*") -> No
                     - have a string "cf" (cloudflare)
                     - have ".com" in them, in either domain, key or value field.
                     - contain "nowsecure"
-        :type pattern: str
         :return:
         :rtype:
         """
@@ -799,7 +795,6 @@ async def load(self, file: PathLike = ".session.dat", pattern: str = ".*") -> No
         load all cookies (or a subset, controlled by `pattern`) from a file created by :py:meth:`~save_cookies`.
 
         :param file:
-        :type file:
         :param pattern: regex style pattern string.
                any cookie that has a  domain, key or value field which matches the pattern will be included.
                default = ".*"  (all)
@@ -808,7 +803,6 @@ async def load(self, file: PathLike = ".session.dat", pattern: str = ".*") -> No
                     - have a string "cf" (cloudflare)
                     - have ".com" in them, in either domain, key or value field.
                     - contain "nowsecure"
-        :type pattern: str
         :return:
         :rtype:
         """

zendriver/core/browser.py

@@ -67,24 +67,13 @@ def __init__(
         :param browser: which browser to use. Can be "chrome", "brave" or "auto". Default is "auto".
         :param browser_args: forwarded to browser executable. eg : ["--some-chromeparam=somevalue", "some-other-param=someval"]
         :param sandbox: disables sandbox
-        :param autodiscover_targets: use autodiscovery of targets
         :param lang: language string to use other than the default "en-US,en;q=0.9"
         :param user_agent: custom user-agent string
         :param expert: when set to True, enabled "expert" mode.
                This conveys, the inclusion of parameters: --disable-web-security ----disable-site-isolation-trials,
                as well as some scripts and patching useful for debugging (for example, ensuring shadow-root is always in "open" mode)
 
         :param kwargs:
-
-        :type user_data_dir: PathLike
-        :type headless: bool
-        :type browser_executable_path: PathLike
-        :type browser: BrowserType
-        :type browser_args: list[str]
-        :type sandbox: bool
-        :type lang: str
-        :type user_agent: str
-        :type kwargs: dict
         """
 
         if not browser_args:
@@ -184,7 +173,6 @@ def add_extension(self, extension_path: PathLike) -> None:
         to a folder (containing the manifest), or extension file (crx)
 
         :param extension_path:
-        :type extension_path:
         :return:
         :rtype:
         """

zendriver/core/config.py

@@ -353,9 +353,7 @@ def add_handler(
         the next time you make network traffic you will see your console print like crazy.
 
         :param event_type_or_domain:
-        :type event_type_or_domain:
         :param handler:
-        :type handler:
 
         :return:
         :rtype:
@@ -417,7 +415,6 @@ def remove_handlers(
     async def aopen(self) -> None:
         """
         opens the websocket connection. should not be called manually by users
-        :param kw:
         :return:
         """
 
@@ -469,7 +466,6 @@ def feed_cdp(self, cdp_obj: Generator[dict[str, Any], dict[str, Any], T]) -> Non
         note: this is not an async method, just a regular method!
 
         :param cdp_obj:
-        :type cdp_obj:
         :return:
         :rtype:
         """
@@ -481,7 +477,6 @@ async def wait(self, t: int | float | None = None) -> None:
         when `t` is provided, ensures waiting for `t` seconds, no matter what.
 
         :param t:
-        :type t:
         :return:
         :rtype:
         """

zendriver/core/connection.py

@@ -32,12 +32,9 @@ def create(
     we don't need to fetch it for every single element.
 
     :param node: cdp dom node representation
-    :type node: cdp.dom.Node
     :param tab: the target object to which this element belongs
-    :type tab: Tab
     :param tree: [Optional] the full node tree to which <node> belongs, enhances performance.
                 when not provided, you need to call `await elem.update()` before using .children / .parent
-    :type tree:
     """
 
     elem = Element(node, tab, tree)
@@ -51,9 +48,7 @@ def __init__(self, node: cdp.dom.Node, tab: Tab, tree: cdp.dom.Node | None = Non
         Represents an (HTML) DOM Element
 
         :param node: cdp dom node representation
-        :type node: cdp.dom.Node
         :param tab: the target object to which this element belongs
-        :type tab: Tab
         """
         if not node:
             raise Exception("node cannot be None")
@@ -218,7 +213,6 @@ def get(self, name: str) -> str | None:
             href = element.get("href")
 
         :param name: The name of the attribute to retrieve.
-        :type name: str
         :return: The value of the attribute, or None if it does not exist.
         :rtype: str | None
         """
@@ -455,7 +449,6 @@ def __call__(self, js_method: str) -> typing.Any:
         calling the element object will call a js method on the object
         eg, element.play() in case of a video element, it will call .play()
         :param js_method:
-        :type js_method:
         :return:
         :rtype:
         """
@@ -477,11 +470,8 @@ async def apply(
             - function myFunction(elem) { alert(elem) }
 
         :param js_function: the js function definition which received this element.
-        :type js_function: str
         :param return_by_value:
-        :type return_by_value:
         :param await_promise: when True, waits for the promise to resolve before returning
-        :type await_promise: bool
         :return:
         :rtype:
         """
@@ -619,16 +609,11 @@ async def mouse_drag(
         drag an element to another element or target coordinates. dragging of elements should be supported  by the site of course
 
 
-        :param destination: another element where to drag to, or a tuple (x,y) of ints representing coordinate
-        :type destination: Element or coordinate as x,y tuple
-
+        :param destination: target Element or coordinates (x,y) to drag to
         :param relative: when True, treats coordinate as relative. for example (-100, 200) will move left 100px and down 200px
-        :type relative:
-
         :param steps: move in <steps> points, this could make it look more "natural" (default 1),
                but also a lot slower.
                for very smooth action use 50-100
-        :type steps: int
         :return:
         :rtype:
         """
@@ -758,13 +743,7 @@ async def send_keys(
 
         hint, if you ever get stuck where using py:meth:`~click`
         does not work, sending the keystroke \\n or \\r\\n or a spacebar work wonders!
-
-        when special_characters is True, it will use grapheme clusters to send the text:
-        if the character is in the printable ASCII range, it sends it using dispatch_key_event.
-        otherwise, it uses insertText, which handles special characters more robustly.
-
         :param text: text to send
-        :param special_characters: when True, uses grapheme clusters to send the text.
         :return: None
         """
         await self.apply("(elem) => elem.focus()")
@@ -897,7 +876,6 @@ async def screenshot_b64(
         When the element is hidden, or has no size, or is otherwise not capturable, a RuntimeError is raised
 
         :param format: jpeg or png (defaults to jpeg)
-        :type format: str
         :param scale: the scale of the screenshot, eg: 1 = size as is, 2 = double, 0.5 is half
         :return: screenshot data as base64 encoded
         :rtype: str
@@ -938,9 +916,7 @@ async def save_screenshot(
         When the element is hidden, or has no size, or is otherwise not capturable, a RuntimeError is raised
 
         :param filename: uses this as the save path
-        :type filename: PathLike
         :param format: jpeg or png (defaults to jpeg)
-        :type format: str
         :param scale: the scale of the screenshot, eg: 1 = size as is, 2 = double, 0.5 is half
         :return: the path/filename of saved screenshot
         :rtype: str
@@ -977,10 +953,7 @@ async def flash(self, duration: typing.Union[float, int] = 0.5) -> None:
         """
         displays for a short time a red dot on the element (only if the element itself is visible)
 
-        :param coords: x,y
-        :type coords: x,y
         :param duration: seconds (default 0.5)
-        :type duration:
         :return:
         :rtype:
         """

zendriver/core/element.py

@@ -13,9 +13,7 @@ class BaseRequestExpectation:
     based on a URL pattern. It sets up handlers for request and response events and provides
     properties to access the request, response, and response body.
     :param tab: The Tab instance to monitor.
-    :type tab: Tab
     :param url_pattern: The URL pattern to match requests and responses.
-    :type url_pattern: Union[str, re.Pattern[str]]
     """
 
     def __init__(self, tab: Connection, url_pattern: Union[str, re.Pattern[str]]):
@@ -36,7 +34,6 @@ async def _request_handler(self, event: cdp.network.RequestWillBeSent) -> None:
         """
         Internal handler for request events.
         :param event: The request event.
-        :type event: cdp.network.RequestWillBeSent
         """
         if re.fullmatch(self.url_pattern, event.request.url):
             self._remove_request_handler()
@@ -47,7 +44,6 @@ async def _response_handler(self, event: cdp.network.ResponseReceived) -> None:
         """
         Internal handler for response events.
         :param event: The response event.
-        :type event: cdp.network.ResponseReceived
         """
         if event.request_id == self.request_id:
             self._remove_response_handler()
@@ -59,7 +55,6 @@ async def _loading_finished_handler(
         """
         Internal handler for loading finished events.
         :param event: The loading finished event.
-        :type event: cdp.network.LoadingFinished
         """
         if event.request_id == self.request_id:
             self._remove_loading_finished_handler()
@@ -159,9 +154,7 @@ class RequestExpectation(BaseRequestExpectation):
     Class for handling request expectations.
     This class extends `BaseRequestExpectation` and provides a property to access the matched request.
     :param tab: The Tab instance to monitor.
-    :type tab: Tab
     :param url_pattern: The URL pattern to match requests.
-    :type url_pattern: Union[str, re.Pattern[str]]
     """
 
     @property
@@ -179,9 +172,7 @@ class ResponseExpectation(BaseRequestExpectation):
     Class for handling response expectations.
     This class extends `BaseRequestExpectation` and provides a property to access the matched response.
     :param tab: The Tab instance to monitor.
-    :type tab: Tab
     :param url_pattern: The URL pattern to match responses.
-    :type url_pattern: Union[str, re.Pattern[str]]
     """
 
     @property