Skip to content

Commit 698a83c

Browse files
authored
Merge pull request #124 from 1985312383/main
Migrate documentation to VitePress
2 parents 4ca6114 + c44107b commit 698a83c

140 files changed

Lines changed: 4225 additions & 2313 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.github/workflows/ci.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ on:
1515
- 'examples/**'
1616
- 'config/**'
1717
- 'tests/**'
18+
- 'pyproject.toml'
19+
- '.github/workflows/ci.yml'
1820
pull_request:
1921
branches: [ main, develop ]
2022
paths:
@@ -23,6 +25,8 @@ on:
2325
- 'examples/**'
2426
- 'config/**'
2527
- 'tests/**'
28+
- 'pyproject.toml'
29+
- '.github/workflows/ci.yml'
2630
release:
2731
types: [published]
2832

@@ -147,9 +151,9 @@ jobs:
147151
148152
- name: Upload coverage to Codecov
149153
if: matrix.os == 'ubuntu-latest' && matrix.python-version == env.PYTHON_VERSION
150-
uses: codecov/codecov-action@v5
154+
uses: codecov/codecov-action@v4
151155
with:
152-
file: ./coverage.xml
156+
files: ./coverage.xml
153157
flags: unittests
154158
name: codecov-umbrella
155159

.github/workflows/deploy.yml

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,37 @@
1-
name: Deploy MkDocs to GitHub Pages
1+
name: Deploy VitePress to GitHub Pages
22

33
on:
44
push:
55
branches:
6-
- main # 你的主分支名称
6+
- main
77
paths:
88
- 'docs/**'
9-
- 'mkdocs.yml'
9+
- 'package.json'
10+
- '.github/workflows/deploy.yml'
1011

1112
jobs:
1213
deploy:
1314
runs-on: ubuntu-latest
1415
steps:
15-
- uses: actions/checkout@v6
16+
- name: Checkout code
17+
uses: actions/checkout@v6
18+
with:
19+
fetch-depth: 0
1620

17-
- name: Set up Python
18-
uses: actions/setup-python@v6
21+
- name: Setup Node.js
22+
uses: actions/setup-node@v4
1923
with:
20-
python-version: '3.x'
24+
node-version: '20'
25+
cache: 'npm'
2126

2227
- name: Install dependencies
23-
run: |
24-
pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocstrings mkdocstrings-python mkdocs-static-i18n
28+
run: npm ci
2529

26-
- name: Build site
27-
run: mkdocs build
30+
- name: Build VitePress site
31+
run: npm run docs:build
2832

2933
- name: Deploy to GitHub Pages
3034
uses: peaceiris/actions-gh-pages@v4
3135
with:
3236
github_token: ${{ secrets.GITHUB_TOKEN }}
33-
publish_dir: ./site
37+
publish_dir: ./docs/.vitepress/dist

.gitignore

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,6 @@ share/python-wheels/
2727
*.egg-info/
2828
.installed.cfg
2929
*.egg
30-
*.pt
31-
*.pth
32-
*.pkl
33-
*.dat
3430
MANIFEST
3531

3632
# PyInstaller
@@ -142,8 +138,10 @@ venv.bak/
142138
# Rope project settings
143139
.ropeproject
144140

145-
# mkdocs documentation
146-
/site
141+
# vitepress documentation
142+
node_modules/
143+
docs/.vitepress/dist
144+
docs/.vitepress/cache
147145

148146
# mypy
149147
.mypy_cache/

README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ English | [简体中文](README_zh.md)
1616

1717
**Torch-RecHub** is a flexible and extensible recommender system framework built with PyTorch. It aims to simplify research and application of recommendation algorithms by providing common model implementations, data processing tools, and evaluation metrics.
1818

19+
![Torch-RecHub Banner](docs/public/img/readme_banner_1.png)
20+
1921
## ✨ Features
2022

2123
* **Modular Design:** Easy to add new models, datasets, and evaluation metrics.

README_zh.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616

1717
**Torch-RecHub** 是一个使用 PyTorch 构建的、灵活且易于扩展的推荐系统框架。它旨在简化推荐算法的研究和应用,提供常见的模型实现、数据处理工具和评估指标。
1818

19+
![Torch-RecHub 横幅](docs/public/img/readme_banner_1.png)
20+
1921
## ✨ 特性
2022

2123
* **模块化设计:** 易于添加新的模型、数据集和评估指标。

config/CONFIG_GUIDE.md

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@
3333
- `config/CONFIG_GUIDE.md` - 本配置完整指南
3434

3535
#### 文档配置
36-
- `mkdocs.yml` - MkDocs文档构建配置
36+
- `docs/.vitepress/config.mts` - VitePress文档构建配置
37+
- `package.json` - Node.js项目配置(包含VitePress脚本)
3738

3839
### 🔧 为什么这样组织?
3940

@@ -95,9 +96,10 @@ torch-rechub项目采用现代化的CI/CD流程,确保代码质量和自动化
9596
当docs目录变更时触发:
9697

9798
#### 1. 文档构建和部署
98-
- 使用MkDocs构建项目文档
99+
- 使用VitePress构建项目文档
99100
- 自动部署到GitHub Pages
100101
- 支持中英文双语文档
102+
- 输出目录:`docs/.vitepress/dist`
101103

102104
### 🚀 触发条件
103105

@@ -137,14 +139,15 @@ torch-rechub项目采用现代化的CI/CD流程,确保代码质量和自动化
137139

138140
| 文件 | 作用 | 说明 |
139141
|------|------|------|
140-
| `mkdocs.yml` | MkDocs文档构建配置 | 文档网站构建配置 |
142+
| `docs/.vitepress/config.mts` | VitePress文档构建配置 | 文档网站构建配置(TypeScript) |
143+
| `package.json` | Node.js项目配置 | VitePress脚本和依赖管理 |
141144

142145
### GitHub Actions配置
143146

144147
| 文件 | 作用 | 说明 |
145148
|------|------|------|
146149
| `.github/workflows/ci.yml` | 主CI流程 | 代码检查、测试、构建、发布 |
147-
| `.github/workflows/deploy.yml` | 文档部署 | MkDocs文档自动部署 |
150+
| `.github/workflows/deploy.yml` | 文档部署 | VitePress文档自动部署到GitHub Pages |
148151
| `.github/dependabot.yml` | 自动依赖更新配置 | 每周检查依赖更新 |
149152

150153
### 模板文件 (双语)
@@ -180,8 +183,14 @@ pre-commit install
180183

181184
### 文档构建
182185
```bash
183-
# 使用docs目录中的配置
184-
mkdocs build
186+
# 开发模式(实时预览)
187+
npm run docs:dev
188+
189+
# 构建生产版本
190+
npm run docs:build
191+
192+
# 预览构建结果
193+
npm run docs:preview
185194
```
186195

187196
### CI/CD工具路径
@@ -615,9 +624,11 @@ git commit -m "fix: resolve code quality issues"
615624
3. 确保版本号唯一
616625

617626
#### 文档构建失败
618-
1. 检查MkDocs配置
619-
2. 验证markdown语法
627+
1. 检查VitePress配置(`docs/.vitepress/config.mts`
628+
2. 验证markdown语法和YAML frontmatter
620629
3. 确保所有链接有效
630+
4. 检查Node.js版本(推荐18+)
631+
5. 运行 `npm install` 确保依赖已安装
621632

622633
### 配置问题
623634

docs/.vitepress/config.mts

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
// https://vitepress.dev/reference/site-config
4+
export default defineConfig({
5+
title: "torch-rechub",
6+
description: "A Lighting Pytorch Framework for Recommendation Models, Easy-to-use and Easy-to-extend.",
7+
head: [
8+
['link', { rel: 'icon', href: '/torch-rechub/favicon.ico' }]
9+
],
10+
// GitHub Pages 部署路径(仓库名)
11+
base: '/torch-rechub/',
12+
13+
// 路径重写:将 en/ 目录映射到根路径
14+
rewrites: {
15+
'en/:rest*': ':rest*'
16+
},
17+
18+
// 多语言配置
19+
locales: {
20+
root: {
21+
label: 'English',
22+
lang: 'en',
23+
title: 'torch-rechub',
24+
description: 'A Lighting Pytorch Framework for Recommendation Models, Easy-to-use and Easy-to-extend.',
25+
themeConfig: {
26+
nav: [
27+
{ text: 'Home', link: '/' },
28+
{ text: 'Introduction', link: '/introduction' },
29+
{ text: 'Documentation', link: '/manual/installation' },
30+
{ text: 'API', link: '/manual/api-reference/basic' },
31+
{ text: 'Blog', link: '/blog/match' },
32+
{ text: 'Contributing', link: '/contributing' }
33+
],
34+
sidebar: {
35+
'/manual/': [
36+
{
37+
text: 'Getting Started',
38+
items: [
39+
{ text: 'Installation', link: '/manual/installation' },
40+
{ text: 'Getting Started', link: '/manual/getting-started' }
41+
]
42+
},
43+
{
44+
text: 'Tutorials',
45+
items: [
46+
{ text: 'Recall Models', link: '/manual/tutorials/matching' },
47+
{ text: 'Ranking Models', link: '/manual/tutorials/ranking' },
48+
{ text: 'Multi-Task Learning', link: '/manual/tutorials/multi-task' }
49+
]
50+
},
51+
{
52+
text: 'API Reference',
53+
items: [
54+
{ text: 'Basic Components', link: '/manual/api-reference/basic' },
55+
{ text: 'Models', link: '/manual/api-reference/models' },
56+
{ text: 'Trainers', link: '/manual/api-reference/trainers' },
57+
{ text: 'Utilities', link: '/manual/api-reference/utils' }
58+
]
59+
},
60+
{
61+
text: 'Others',
62+
items: [
63+
{ text: 'FAQ', link: '/manual/faq' }
64+
]
65+
}
66+
],
67+
'/blog/': [
68+
{
69+
text: 'Blog',
70+
items: [
71+
{ text: 'Matching Training Guide', link: '/blog/match' },
72+
{ text: 'Ranking Training Guide', link: '/blog/rank' }
73+
]
74+
}
75+
]
76+
},
77+
socialLinks: [
78+
{ icon: 'github', link: 'https://github.com/datawhalechina/torch-rechub' }
79+
]
80+
}
81+
},
82+
zh: {
83+
label: '中文',
84+
lang: 'zh-CN',
85+
title: 'torch-rechub',
86+
description: '一个基于 PyTorch 的易用、可扩展且高性能的推荐系统框架',
87+
themeConfig: {
88+
nav: [
89+
{ text: '首页', link: '/zh/' },
90+
{ text: '项目介绍', link: '/zh/introduction' },
91+
{ text: '项目文档', link: '/zh/manual/installation' },
92+
{ text: 'API', link: '/zh/manual/api-reference/basic' },
93+
{ text: '博客', link: '/zh/blog/match' },
94+
{ text: '贡献指南', link: '/zh/contributing' }
95+
],
96+
sidebar: {
97+
'/zh/manual/': [
98+
{
99+
text: '入门指南',
100+
items: [
101+
{ text: '安装指南', link: '/zh/manual/installation' },
102+
{ text: '快速开始', link: '/zh/manual/getting-started' }
103+
]
104+
},
105+
{
106+
text: '教程',
107+
items: [
108+
{ text: '召回模型', link: '/zh/manual/tutorials/matching' },
109+
{ text: '排序模型', link: '/zh/manual/tutorials/ranking' },
110+
{ text: '多任务学习', link: '/zh/manual/tutorials/multi-task' }
111+
]
112+
},
113+
{
114+
text: 'API 参考',
115+
items: [
116+
{ text: '基础组件', link: '/zh/manual/api-reference/basic' },
117+
{ text: '模型', link: '/zh/manual/api-reference/models' },
118+
{ text: '训练器', link: '/zh/manual/api-reference/trainers' },
119+
{ text: '工具类', link: '/zh/manual/api-reference/utils' }
120+
]
121+
},
122+
{
123+
text: '其他',
124+
items: [
125+
{ text: '常见问题', link: '/zh/manual/faq' },
126+
{ text: '参考资料', link: '/zh/参考资料/参考资料' }
127+
]
128+
}
129+
],
130+
'/zh/blog/': [
131+
{
132+
text: '博客',
133+
items: [
134+
{ text: '召回模型训练指南', link: '/zh/blog/match' },
135+
{ text: '排序模型训练指南', link: '/zh/blog/rank' },
136+
{ text: 'HSTU 模型复现', link: '/zh/blog/hstu_reproduction' }
137+
]
138+
}
139+
]
140+
},
141+
socialLinks: [
142+
{ icon: 'github', link: 'https://github.com/datawhalechina/torch-rechub' }
143+
]
144+
}
145+
}
146+
},
147+
148+
themeConfig: {
149+
logo: '/img/logo.png'
150+
}
151+
})

0 commit comments

Comments
 (0)