规范化，api文档搭建

.github/workflows/docs-and-deploy.yml

@@ -0,0 +1,55 @@
+name: 构建并部署文档到 GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: 设置Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+
+      - name: 安装依赖
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install -r requirements.txt
+          
+      - name: 生成 API 文档
+        run: |
+          sphinx-apidoc -o docs/source/modules ../ha4t/ --extensions EXTENSIONS -e
+          
+      - name: 构建文档
+        run: |
+          cd docs
+          make html
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/build/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,6 @@
+six
+sphinx
+recommonmark
+sphinx-markdown-tables
+mock
+sphinx_rtd_theme

docs/source/README_MORE.rst

@@ -0,0 +1,48 @@
+HA4T
+=======
+
+**HA4T是一个跨平台的UI自动化框架，支持Android、iOS和Web应用，能够有效地处理webview。该框架旨在为开发者提供灵活、强大的自动化测试解决方案，帮助用户快速实现自动化测试的目标。**
+
+快速开始
+---------------
+*   **跨平台支持：**适用于iOS、Android和Web应用**
+*   **多种定位方式：**支持图像识别、OCR文字识别、原生控件定位等**
+*   **灵活的操作API：**提供点击、滑动、输入等常用操作**
+
+安装
+------------
+可以通过pip安装
+
+.. code:: shell
+
+    pip install -U ha4t
+
+You can also install it from Git repository.
+
+.. code:: shell
+
+    pip install -U git+https://github.com/1103837067/ha4t.git
+
+简单示例:
+------------
+.. code-block:: python
+
+   from ha4t.api import *
+   
+   # 连接设备  
+   device = Device("android")
+   
+   # 启动应用
+   start_app("com.example.app")
+   
+   # 点击元素
+   click("登录")
+   
+   # 输入文本
+   input("用户名", "testuser")
+   
+   # 等待元素出现
+   wait("登录成功")
+   
+   # 断言文本存在
+   assert "欢迎回来" in get_page_text()

docs/source/conf.py

@@ -0,0 +1,56 @@
+import sys
+import os
+import mock
+
+# 将项目根目录添加到系统路径
+sys.path.insert(0, os.path.abspath('../..'))
+
+# 模拟未安装的模块
+MOCK_MODULES = ['cv2', 'numpy', 'PIL', 'wda', 'uiautomator2', 'paddleocr', "PIL.Image"]
+for mod_name in MOCK_MODULES:
+    sys.modules[mod_name] = mock.MagicMock()
+
+# 为 cv2 模块添加 __version__ 属性
+sys.modules['cv2'].__version__ = '4.5.0'
+
+# Sphinx 扩展
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.napoleon',
+    'recommonmark',
+    'sphinx_markdown_tables',
+]
+
+# 源文件后缀
+source_suffix = ['.rst', '.md']
+
+# 主文档
+master_doc = 'index'
+
+# 项目信息
+project = 'HA4T'
+copyright = '2024, caishilong'
+author = 'caishilong'
+
+# 语言设置
+language = 'zh_CN'
+
+# HTML 主题
+html_theme = 'sphinx_rtd_theme'
+
+# autodoc 配置
+autodoc_member_order = 'bysource'
+add_module_names = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# 如果需要支持多语言
+# locale_dirs = ['locale/']
+# gettext_compact = False

docs/source/index.rst

@@ -0,0 +1,78 @@
+.. HA4T 文档主文件，由
+   sphinx-quickstart 于 2023 年 10 月 12 日创建。
+   您可以根据自己的需要完全自定义此文件，但至少应包含根 `toctree` 指令。
+
+欢迎使用 HA4T 文档!
+================================
+
+HA4T 是一个强大的 UI 自动化测试框架，支持 Android 和 iOS 平台。它提供了简单易用的 API，让您能够快速编写和执行自动化测试脚本。
+
+主要特性:
+
+- 支持 Android 和 iOS 平台
+- 提供直观的元素定位和操作 API  
+- 内置 OCR 文字识别功能
+- 支持图像识别和模板匹配
+- 集成 CDP 调试功能，支持 Web 应用测试
+- 丰富的辅助功能，如截图、日志记录等
+
+快速开始
+---------
+
+安装 HA4T:
+
+.. code-block:: bash
+
+   pip install ha4t
+
+================================
+
+.. toctree::
+   :maxdepth: 4
+   :caption: 快速开始
+
+   README_MORE.rst
+================================
+
+.. toctree::
+   :maxdepth: 4
+   :caption: 配置
+
+   modules/ha4t.config
+
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 原生元素操作
+
+   modules/ha4t.api
+
+
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Webview 操作
+
+   modules/ha4t.cdp.cdp
+   modules/ha4t.cdp.server
+
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 工具模块
+
+   modules/ha4t.utils.log_utils
+
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 所有模块
+
+   modules/modules
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

ha4t/__init__.py

@@ -1,13 +1,39 @@
 __version__ = "0.0.3"
+__all__ = ["__version__", "connect", "device", "driver", "Device", "screen_size"]
 
-from ha4t.config import Config as CF
+import json
+from typing import Optional, Any, Union, Tuple
+import wda
+from ha4t.utils.log_utils import log_out
+import uiautomator2 as u2
+from ha4t.config import Config as _CF
 
+class Device:
+    def __init__(self, platform: str, device_id: Optional[str] = None, port: int = 8100):
+        self.adb: Optional[Any] = None
+        if platform == "ios":
+            try:
+                _CF.DEVICE_SERIAL = device_id or wda.list_devices()[0].serial
+            except IndexError:
+                raise IndexError("未找到设备，请检查连接")
+            self.driver: wda.Client = wda.USBClient(udid=_CF.DEVICE_SERIAL, port=port)
+        else:
+            self.driver: u2.Device = u2.connect(serial=device_id)
+            self.adb = self.driver.adb_device
+            _CF.DEVICE_SERIAL = self.adb.serial
+        self.device_info = json.dumps(self.driver.info, ensure_ascii=False, indent=4)
+        log_out(f"设备信息：{self.device_info}")
 
-def connect(device_serial="", android_package_name=None, android_activity_name=None, platform="android"):
-    CF.PLATFORM = platform
-    CF.DEVICE_SERIAL = device_serial
-    CF.ANDROID_PACKAGE_NAME = android_package_name
-    CF.ANDROID_ACTIVITY_NAME = android_activity_name
-
+device: Device = None
+driver: Union[u2.Device, wda.Client] = None
+screen_size: Tuple[int, int] = (0, 0)
 
-__all__ = ["__version__", "connect"]
+def connect(device_serial="", android_package_name=None, android_activity_name=None, platform="android"):
+    device.__dict__.update(Device(_CF.PLATFORM, device_id=_CF.DEVICE_SERIAL).__dict__)
+    driver.__dict__.update(device.driver.__dict__)
+    screen_size.__dict__.update(driver.window_size().__dict__)
+    _CF.SCREEN_WIDTH, _CF.SCREEN_HEIGHT = screen_size
+    _CF.PLATFORM = platform
+    _CF.DEVICE_SERIAL = device_serial
+    _CF.ANDROID_PACKAGE_NAME = android_package_name
+    _CF.ANDROID_ACTIVITY_NAME = android_activity_name