Skip to content

Commit 4eef55f

Browse files
taven-liutaven-liu
authored
[vibe coding] feat: support multi-version docs (#159)
<!-- Thank you for contributing to OceanBase! Please feel free to ping the maintainers for the review! --> ## Summary close #104 <!-- Please clearly and concisely describe the purpose of this pull request. If this pull request resolves an issue, please link it via "close #xxx" or "fix #xxx". --> ## Solution Description 1. 多版本文档构建系统 - 集成 sphinx-multiversion 扩展，支持为多个分支和标签构建文档 - 配置了版本白名单规则： - 标签格式：v *.*.*（如 v1.0.0, v1.1.0） - 分支：main 和 develop - 自动创建重定向页面，默认跳转到 develop 版本 2. Makefile 新增命令 - `make docs-multiversion`：构建所有版本的文档 - `make docs-serve`：启动支持自动重载的开发服务器 - `make docs`：单版本构建（已更新注释） <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Multi-version documentation build and a local doc server with auto-reload for live previews * Version selector dropdown in the docs UI to switch between documentation versions * **Documentation** * New styling and banners for version-aware documentation and a redirect to the latest version for easy access <sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub> <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 175c55f commit 4eef55f

5 files changed

Lines changed: 168 additions & 1 deletion

File tree

‎Makefile‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,20 @@ test-integration-embedded: ## Run embedded integration tests
3434
@$(UV) run pytest tests/integration_tests/ -v --log-cli-level=INFO -k embedded
3535

3636
.PHONY: docs
37-
docs: ## Build documentation
37+
docs: ## Build documentation (single version)
3838
@echo ">> Building documentation"
3939
@$(UV) run sphinx-build -b html docs docs/_build/html
4040

41+
.PHONY: docs-multiversion
42+
docs-multiversion: ## Build multi-version documentation
43+
@echo ">> Building multi-version documentation"
44+
@bash docs/build_multiversion.sh
45+
46+
.PHONY: docs-serve
47+
docs-serve: ## Serve documentation with auto-reload
48+
@echo ">> Starting documentation server"
49+
@$(UV) run sphinx-autobuild docs docs/_build/html --host 127.0.0.1 --port 8000
50+
4151
.PHONY: build
4252
build: ## Build package
4353
@echo ">> Building package"

‎docs/_static/custom.css‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
/* 版本选择器下拉框样式 - 放在左侧导航栏搜索框下方 */
2+
.version-selector-dropdown {
3+
display: flex;
4+
align-items: center;
5+
gap: 8px;
6+
margin-top: 8px;
7+
border-radius: 50px;
8+
}
9+
10+
.version-selector-dropdown label {
11+
font-size: 13px;
12+
font-weight: 600;
13+
color: #fff;
14+
margin: 0;
15+
white-space: nowrap;
16+
}
17+
18+
.version-selector-dropdown select {
19+
flex: 1;
20+
padding: 6px 10px;
21+
font-size: 13px;
22+
color: #404040;
23+
background-color: #fff;
24+
border: 1px solid #d0d0d0;
25+
border-radius: 4px;
26+
cursor: pointer;
27+
outline: none;
28+
transition: all 0.2s ease;
29+
}
30+
31+
.version-selector-dropdown select:hover {
32+
border-color: #2980b9;
33+
}
34+
35+
.version-selector-dropdown select:focus {
36+
border-color: #2980b9;
37+
box-shadow: 0 0 0 2px rgba(41, 128, 185, 0.1);
38+
}
39+
40+
/* RTD 主题版本横幅样式 - 隐藏左下角的版本选择器 */
41+
.rst-versions {
42+
display: none !important;
43+
}
44+
45+
/* 版本警告横幅 */
46+
.version-warning {
47+
padding: 10px 15px;
48+
margin-bottom: 20px;
49+
background-color: #fff3cd;
50+
border: 1px solid #ffeaa7;
51+
border-radius: 4px;
52+
color: #856404;
53+
}
54+
55+
.version-warning strong {
56+
font-weight: bold;
57+
}
58+
59+
.version-warning a {
60+
color: #856404;
61+
text-decoration: underline;
62+
}
63+
64+
.version-warning a:hover {
65+
color: #533f03;
66+
}

‎docs/_templates/layout.html‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{% extends "!layout.html" %}
2+
3+
{# 在左侧导航栏的搜索框下方插入版本选择器 #}
4+
{% block sidebartitle %}
5+
{{ super() }}
6+
{% if versions %}
7+
<div class="version-selector-dropdown">
8+
<label for="version-select">版本:</label>
9+
<select id="version-select" onchange="window.location.href=this.value">
10+
{% for item in versions %}
11+
<option value="{{ item.url }}" {% if item.name == current_version %}selected{% endif %}>
12+
{{ item.name }}{% if item.name == current_version %} (当前){% elif item.is_released %} (稳定){% endif %}
13+
</option>
14+
{% endfor %}
15+
</select>
16+
</div>
17+
{% endif %}
18+
{% endblock %}

‎docs/build_multiversion.sh‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
#!/bin/bash
2+
# 构建多版本文档的脚本
3+
4+
set -e
5+
6+
# 颜色输出
7+
GREEN='\033[0;32m'
8+
BLUE='\033[0;34m'
9+
NC='\033[0m' # No Color
10+
11+
echo -e "${BLUE}开始构建多版本文档...${NC}"
12+
13+
# 确保在项目根目录
14+
cd "$(dirname "$0")/.."
15+
16+
# 激活虚拟环境（如果存在）
17+
if [ -d ".venv" ]; then
18+
echo -e "${GREEN}激活虚拟环境...${NC}"
19+
source .venv/bin/activate
20+
fi
21+
22+
# 清理旧的构建文件
23+
echo -e "${GREEN}清理旧的构建文件...${NC}"
24+
rm -rf docs/_build/html
25+
26+
# 使用 sphinx-multiversion 构建文档
27+
echo -e "${GREEN}使用 sphinx-multiversion 构建文档...${NC}"
28+
sphinx-multiversion docs docs/_build/html
29+
30+
# 创建重定向到最新版本的 index.html
31+
echo -e "${GREEN}创建重定向页面...${NC}"
32+
cat > docs/_build/html/index.html << 'EOF'
33+
<!DOCTYPE html>
34+
<html>
35+
<head>
36+
<title>Redirecting to latest version</title>
37+
<meta charset="utf-8">
38+
<meta http-equiv="refresh" content="0; url=./develop/index.html">
39+
<link rel="canonical" href="./develop/index.html">
40+
</head>
41+
<body>
42+
<p>Redirecting to <a href="./develop/index.html">latest version</a>...</p>
43+
</body>
44+
</html>
45+
EOF
46+
47+
echo -e "${BLUE}多版本文档构建完成！${NC}"
48+
echo -e "${GREEN}文档位置: docs/_build/html${NC}"
49+
echo -e "${GREEN}可以使用以下命令启动本地服务器查看:${NC}"
50+
echo -e " cd docs/_build/html && python -m http.server 8000"

‎docs/conf.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
"sphinx.ext.viewcode",
2727
"sphinx.ext.napoleon",
2828
"myst_parser",
29+
"sphinx_multiversion",
2930
]
3031

3132
# Enable Markdown in docstrings
@@ -59,3 +60,25 @@
5960
# HTML theme
6061
html_theme = "sphinx_rtd_theme"
6162
html_static_path = ["_static"]
63+
html_css_files = [
64+
"custom.css",
65+
]
66+
67+
# Sphinx-multiversion configuration
68+
# 配置要包含的分支和标签
69+
smv_tag_whitelist = r"^v\d+\.\d+\.\d+$" # 匹配 v1.0.0 格式的标签
70+
smv_branch_whitelist = r"^(main|develop)$" # 包含 main 和 develop 分支
71+
smv_remote_whitelist = r"^origin$" # 只使用 origin 远程仓库
72+
smv_released_pattern = r"^refs/tags/.*$" # 标记已发布的版本
73+
74+
# 自定义模板路径
75+
templates_path = ["_templates"]
76+
77+
# 版本横幅配置
78+
html_context = {
79+
"display_github": True,
80+
"github_user": "oceanbase",
81+
"github_repo": "pyseekdb",
82+
"github_version": "develop",
83+
"conf_py_path": "/docs/",
84+
}

0 commit comments

Comments
 (0)