merge from functions from develop to release/v1.1.0

.github/workflows/ci.yml

@@ -34,7 +34,7 @@
       - name: Run checks
         run: make check
 
-  unit-test:
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
@@ -45,31 +45,64 @@
         with:
           python-version: '3.11'
 
+      - name: Build package
+        run: make build
+
+      - name: Verify build artifacts
+        run: |
+          ls -la dist/
+          # Verify both sdist and wheel are created
+          test -f dist/*.tar.gz || (echo "Source distribution not found" && exit 1)
+          test -f dist/*.whl || (echo "Wheel not found" && exit 1)
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  unit-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.14']
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
       - name: Install depencies for unit tests
         run: |
           uv run pip install openai sentence-transformers torch torchvision torchaudio boto3 litellm voyageai
 
       - name: Run unit tests
         run: |
           if [ "${{ env.RUNNER_DEBUG }}" = "true" ]; then
             log_level=DEBUG
           else
             log_level=INFO
           fi
+          set -o pipefail
           uv run pytest tests/unit_tests/ -v --log-cli-level=${log_level} | tee pytest.log
-          tail -n 1 pytest.log | grep -q 'failed' && exit 1 || exit 0
+          tail -n 1 pytest.log | grep '=======' | grep 'passed' |grep -q 'failed' && exit 1 || exit 0
 
       - name: Run integration tests without any test mode
         run: |
           if [ "${{ env.RUNNER_DEBUG }}" = "true" ]; then
             log_level=DEBUG
           else
             log_level=INFO
           fi
+          set -o pipefail
           uv run pytest tests/integration_tests/ -v --log-cli-level=${log_level} -k "not server and not embedded and not oceanbase" | tee pytest.log
-          tail -n 1 pytest.log | grep -q 'failed' && exit 1 || exit 0
+          tail -n 1 pytest.log | grep '=======' | grep 'passed' | grep -q 'failed' && exit 1 || exit 0
 
   integration-test:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false  # Allow other jobs to continue if one fails
@@ -128,5 +161,6 @@
           else
             log_level=INFO
           fi
+          set -o pipefail
           uv run pytest tests/integration_tests/ -v --log-cli-level=${log_level} -k "${{ matrix.test_mode }}" | tee pytest.log
-          tail -n 1 pytest.log | grep -q 'failed' && exit 1 || exit 0
+          tail -n 1 pytest.log | grep '=======' | grep 'passed' | grep -q 'failed' && exit 1 || exit 0

Makefile

@@ -34,10 +34,20 @@ test-integration-embedded: ## Run embedded integration tests
 	@$(UV) run pytest tests/integration_tests/ -v --log-cli-level=INFO -k embedded
 
 .PHONY: docs
-docs: ## Build documentation
+docs: ## Build documentation (single version)
 	@echo ">> Building documentation"
 	@$(UV) run sphinx-build -b html docs docs/_build/html
 
+.PHONY: docs-multiversion
+docs-multiversion: ## Build multi-version documentation
+	@echo ">> Building multi-version documentation"
+	@bash docs/build_multiversion.sh
+
+.PHONY: docs-serve
+docs-serve: ## Serve documentation with auto-reload
+	@echo ">> Starting documentation server"
+	@$(UV) run sphinx-autobuild docs docs/_build/html --host 127.0.0.1 --port 8000
+
 .PHONY: build
 build: ## Build package
 	@echo ">> Building package"

README.md

@@ -18,7 +18,8 @@ To achieve the above design goals, this SDK follows the following design princip
 6. [DQL Operations](#5-dql-operations)
 7. [Embedding Functions](#6-embedding-functions)
 8. [RAG Demo](#rag-demo)
-9. [Testing](#testing)
+9. [Development](#development)
+10. [Testing](#testing)
 
 ## Installation
 
@@ -1156,31 +1157,75 @@ The demo supports three embedding modes:
 
 For detailed instructions, see [demo/rag/README.md](demo/rag/README.md).
 
-## Testing
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) as the package manager with [pdm-backend](https://pdm-backend.fming.dev/) as the build backend. All common development tasks are unified through the `Makefile`.
+
+### Prerequisites
+
+Install uv:
 
 ```bash
-# Run all tests (unit + integration)
-python3 -m pytest -v
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 
-# Run tests with log output
-python3 -m pytest -v -s
+# Or via pip
+pip install uv
+```
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/oceanbase/pyseekdb.git
+cd pyseekdb
+
+# Install dependencies and pre-commit hooks
+make install
+```
 
-# Run unit tests only
-python3 -m pytest tests/unit_tests/ -v
+### Make Targets
+
+Run `make help` to see all available targets:
+
+```bash
+make help              # Show all available targets
+make install           # Install dependencies and pre-commit hooks
+make check             # Run code quality tools (lint, format check)
+make test              # Run unit tests
+make test-integration-embedded  # Run embedded integration tests
+make build             # Build the package
+make docs              # Build documentation
+make clean             # Clean build artifacts
+```
+
+### Build Artifacts
+
+After running `make build`, the distribution files will be in the `dist/` directory:
+- `pyseekdb-<version>.tar.gz` - Source distribution
+- `pyseekdb-<version>-py3-none-any.whl` - Wheel distribution
+
+## Testing
+
+```bash
+# Run unit tests
+make test
 
-# Run integration tests only
-python3 -m pytest tests/integration_tests/ -v
+# Run embedded integration tests
+make test-integration-embedded
 
-# Run integration tests for specific mode
-python3 -m pytest tests/integration_tests/ -v -k "embedded"   # embedded mode
-python3 -m pytest tests/integration_tests/ -v -k "server"     # server mode (requires seekdb server)
-python3 -m pytest tests/integration_tests/ -v -k "oceanbase"  # oceanbase mode (requires OceanBase)
+# Run specific tests with uv run
+uv run pytest tests/integration_tests/ -v -k "server"     # server mode (requires seekdb server)
+uv run pytest tests/integration_tests/ -v -k "oceanbase"  # oceanbase mode (requires OceanBase)
 
 # Run specific test file
-python3 -m pytest tests/integration_tests/test_collection_query.py -v
+uv run pytest tests/integration_tests/test_collection_query.py -v
 
 # Run specific test function
-python3 -m pytest tests/integration_tests/test_collection_query.py::TestCollectionQuery::test_collection_query -v
+uv run pytest tests/integration_tests/test_collection_query.py::TestCollectionQuery::test_collection_query -v
 ```
 
 ## License

docs/_static/custom.css

@@ -0,0 +1,66 @@
+/* 版本选择器下拉框样式 - 放在左侧导航栏搜索框下方 */
+.version-selector-dropdown {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-top: 8px;
+    border-radius: 50px;
+}
+
+.version-selector-dropdown label {
+    font-size: 13px;
+    font-weight: 600;
+    color: #fff;
+    margin: 0;
+    white-space: nowrap;
+}
+
+.version-selector-dropdown select {
+    flex: 1;
+    padding: 6px 10px;
+    font-size: 13px;
+    color: #404040;
+    background-color: #fff;
+    border: 1px solid #d0d0d0;
+    border-radius: 4px;
+    cursor: pointer;
+    outline: none;
+    transition: all 0.2s ease;
+}
+
+.version-selector-dropdown select:hover {
+    border-color: #2980b9;
+}
+
+.version-selector-dropdown select:focus {
+    border-color: #2980b9;
+    box-shadow: 0 0 0 2px rgba(41, 128, 185, 0.1);
+}
+
+/* RTD 主题版本横幅样式 - 隐藏左下角的版本选择器 */
+.rst-versions {
+    display: none !important;
+}
+
+/* 版本警告横幅 */
+.version-warning {
+    padding: 10px 15px;
+    margin-bottom: 20px;
+    background-color: #fff3cd;
+    border: 1px solid #ffeaa7;
+    border-radius: 4px;
+    color: #856404;
+}
+
+.version-warning strong {
+    font-weight: bold;
+}
+
+.version-warning a {
+    color: #856404;
+    text-decoration: underline;
+}
+
+.version-warning a:hover {
+    color: #533f03;
+}

docs/_templates/layout.html

@@ -0,0 +1,18 @@
+{% extends "!layout.html" %}
+
+{# 在左侧导航栏的搜索框下方插入版本选择器 #}
+{% block sidebartitle %}
+  {{ super() }}
+  {% if versions %}
+  <div class="version-selector-dropdown">
+    <label for="version-select">版本:</label>
+    <select id="version-select" onchange="window.location.href=this.value">
+      {% for item in versions %}
+      <option value="{{ item.url }}" {% if item.name == current_version %}selected{% endif %}>
+        {{ item.name }}{% if item.name == current_version %} (当前){% elif item.is_released %} (稳定){% endif %}
+      </option>
+      {% endfor %}
+    </select>
+  </div>
+  {% endif %}
+{% endblock %}

docs/build_multiversion.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# 构建多版本文档的脚本
+
+set -e
+
+# 颜色输出
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}开始构建多版本文档...${NC}"
+
+# 确保在项目根目录
+cd "$(dirname "$0")/.."
+
+# 激活虚拟环境（如果存在）
+if [ -d ".venv" ]; then
+    echo -e "${GREEN}激活虚拟环境...${NC}"
+    source .venv/bin/activate
+fi
+
+# 清理旧的构建文件
+echo -e "${GREEN}清理旧的构建文件...${NC}"
+rm -rf docs/_build/html
+
+# 使用 sphinx-multiversion 构建文档
+echo -e "${GREEN}使用 sphinx-multiversion 构建文档...${NC}"
+sphinx-multiversion docs docs/_build/html
+
+# 创建重定向到最新版本的 index.html
+echo -e "${GREEN}创建重定向页面...${NC}"
+cat > docs/_build/html/index.html << 'EOF'
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Redirecting to latest version</title>
+  <meta charset="utf-8">
+  <meta http-equiv="refresh" content="0; url=./develop/index.html">
+  <link rel="canonical" href="./develop/index.html">
+</head>
+<body>
+  <p>Redirecting to <a href="./develop/index.html">latest version</a>...</p>
+</body>
+</html>
+EOF
+
+echo -e "${BLUE}多版本文档构建完成！${NC}"
+echo -e "${GREEN}文档位置: docs/_build/html${NC}"
+echo -e "${GREEN}可以使用以下命令启动本地服务器查看:${NC}"
+echo -e "  cd docs/_build/html && python -m http.server 8000"

docs/conf.py

@@ -26,6 +26,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "myst_parser",
+    "sphinx_multiversion",
 ]
 
 # Enable Markdown in docstrings
@@ -59,3 +60,25 @@
 # HTML theme
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+html_css_files = [
+    "custom.css",
+]
+
+# Sphinx-multiversion configuration
+# 配置要包含的分支和标签
+smv_tag_whitelist = r"^v\d+\.\d+\.\d+$"  # 匹配 v1.0.0 格式的标签
+smv_branch_whitelist = r"^(main|develop)$"  # 包含 main 和 develop 分支
+smv_remote_whitelist = r"^origin$"  # 只使用 origin 远程仓库
+smv_released_pattern = r"^refs/tags/.*$"  # 标记已发布的版本
+
+# 自定义模板路径
+templates_path = ["_templates"]
+
+# 版本横幅配置
+html_context = {
+    "display_github": True,
+    "github_user": "oceanbase",
+    "github_repo": "pyseekdb",
+    "github_version": "develop",
+    "conf_py_path": "/docs/",
+}