未验证 提交 fe061d05 编写于 作者: 羽飞's avatar 羽飞 提交者: GitHub

Document (#197)

### What problem were solved in this pull request?

Problem:
当前生成的github pages不太整洁方便,可以优化一下

### What is changed and how it works?
改用mdbook生成文档,并整理文档目录,调整链接
上级 93b79cc6
# Sample workflow for building and deploying a Jekyll site to GitHub Pages
name: Deploy Jekyll with GitHub Pages dependencies preinstalled
# Sample workflow for building and deploying a mdBook site to GitHub Pages
#
# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
#
name: Deploy mdBook site to Pages
on:
# Runs on pushes targeting the default branch
......@@ -25,11 +28,23 @@ jobs:
# Build job
build:
runs-on: ubuntu-latest
env:
MDBOOK_VERSION: 0.4.21
steps:
- name: Checkout
uses: actions/checkout@v3
with:
submodules: false
- uses: actions/checkout@v3
- name: Install mdBook
run: |
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
rustup update
cargo install --version ${MDBOOK_VERSION} mdbook
- name: Setup Pages
id: pages
uses: actions/configure-pages@v3
- name: Build with mdBook
run: mdbook build
working-directory: ./docs
- name: Doxygen Action
uses: mattnotmitt/doxygen-action@v1.9.5
......@@ -37,17 +52,10 @@ jobs:
working-directory: .
doxyfile-path: ./Doxyfile
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Build with Jekyll
uses: actions/jekyll-build-pages@v1
with:
source: ./
destination: ./_site
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: docs/book
# Deployment job
deploy:
......
......@@ -22,4 +22,5 @@ compile_commands.json
GRTAGS
GPATH
GTAGS
docs/book
#*#
......@@ -6,17 +6,17 @@ OceanBase 社区热情欢迎每一位对数据库技术热爱的开发者,期
为了帮助开发者更好的上手并学习 miniob, 建议阅读:
1. [miniob 框架介绍](https://github.com/oceanbase/miniob/blob/main/docs/miniob-introduction.md)
2. [如何编译 miniob 源码](https://github.com/oceanbase/miniob/blob/main/docs/how_to_build.md)
3. [开发环境搭建(本地调试, 适用 Linux 和 Mac)](https://github.com/oceanbase/miniob/blob/main/docs/how_to_dev_miniob_by_vscode.md)
4. [开发环境搭建(远程调试, 适用于 Window, Linux 和 Mac)](https://github.com/oceanbase/miniob/blob/main/docs/how_to_dev_in_docker_container_by_vscode.md)
5. [miniob 词法语法解析开发与测试](docs/miniob-sql-parser.md)
1. [miniob 框架介绍](docs/src/miniob-introduction.md)
2. [如何编译 miniob 源码](docs/src/how_to_build.md)
3. [开发环境搭建(本地调试, 适用 Linux 和 Mac)](docs/src/dev-env/how_to_dev_miniob_by_vscode.md)
4. [开发环境搭建(远程调试, 适用于 Window, Linux 和 Mac)](docs/src/dev-env/how_to_dev_in_docker_container_by_vscode.md)
5. [miniob 文档汇总](docs/src/SUMMARY.md)
更多的文档, 可以参考 [docs](https://github.com/oceanbase/miniob/tree/main/docs), 为了帮助大家更好的学习数据库基础知识, OceanBase 社区提供了一系列教程, 建议学习:
1. [《从0到1数据库内核实战教程》 视频教程](https://open.oceanbase.com/activities/4921877?id=4921946)
2. [《从0到1数据库内核实战教程》 基础讲义](https://github.com/oceanbase/kernel-quickstart)
3. [《数据库管理系统实现》 华中科技大学实现教材](https://github.com/oceanbase/miniob/blob/main/docs/lectures/index.md)
3. [《数据库管理系统实现》 华中科技大学实现教材](docs/src/lectures/index.md)
## 如何找到一个合适issue
......
......@@ -68,7 +68,7 @@ PROJECT_LOGO =
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
OUTPUT_DIRECTORY = docs/doxy
OUTPUT_DIRECTORY = docs/book/design/doxy
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
# sub-directories (in 2 levels) under the output directory of each output format
......@@ -120,7 +120,7 @@ OUTPUT_LANGUAGE = Chinese
# documentation (similar to Javadoc). Set to NO to disable this.
# The default value is: YES.
BRIEF_MEMBER_DESC = NO
BRIEF_MEMBER_DESC = YES
# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief
# description of a member or function before the detailed description
......@@ -524,13 +524,13 @@ EXTRACT_ALL = NO
# be included in the documentation.
# The default value is: NO.
EXTRACT_PRIVATE = NO
EXTRACT_PRIVATE = YES
# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
# methods of a class will be included in the documentation.
# The default value is: NO.
EXTRACT_PRIV_VIRTUAL = NO
EXTRACT_PRIV_VIRTUAL = YES
# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
# scope will be included in the documentation.
......@@ -542,7 +542,7 @@ EXTRACT_PACKAGE = NO
# included in the documentation.
# The default value is: NO.
EXTRACT_STATIC = NO
EXTRACT_STATIC = YES
# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
# locally in source files will be included in the documentation. If set to NO,
......
# miniob 概述
# MiniOB 概述
miniob[OceanBase](https://github.com/oceanbase/oceanbase) 与华中科技大学联合开发的、面向"零"基础同学的数据库入门学习项目。
MiniOB[OceanBase](https://github.com/oceanbase/oceanbase) 与华中科技大学联合开发的、面向"零"基础同学的数据库入门学习项目。
miniob 设计的目标是面向在校学生、数据库从业者、爱好者,或者对基础技术有兴趣的爱好者, 整体代码量少,易于上手并学习, 是一个系统性的数据库学习项目。miniob 设置了一系列由浅入深的题目,以帮助同学们"零"基础入门, 让同学们快速了解数据库并深入学习数据库内核,期望通过相关训练之后,能够熟练掌握数据库内核模块的功能与协同关系, 并能够在使用数据库时,设计出高效的 SQL 。miniob 为了更好的学习数据库实现原理, 对诸多模块都做了简化,比如不考虑并发操作, 安全特性, 复杂的事物管理等功能。
(注意:此代码仅供学习使用,请勿用于生产项目。)
MiniOB 设计的目标是面向在校学生、数据库从业者、爱好者,或者对基础技术有兴趣的爱好者, 整体代码量少,易于上手并学习, 是一个系统性的数据库学习项目。miniob 设置了一系列由浅入深的题目,以帮助同学们"零"基础入门, 让同学们快速了解数据库并深入学习数据库内核,期望通过相关训练之后,能够熟练掌握数据库内核模块的功能与协同关系, 并能够在使用数据库时,设计出高效的 SQL 。miniob 为了更好的学习数据库实现原理, 对诸多模块都做了简化,比如不考虑并发操作, 安全特性, 复杂的事物管理等功能。
## 快速上手
为了帮助开发者更好的上手并学习 miniob, 建议阅读:
1. [miniob 框架介绍](docs/miniob-introduction.md)
2. [如何编译 miniob 源码](docs/how_to_build.md)
2. [如何编译 MiniOB 源码](docs/how_to_build.md)
3. [使用 GitPod 开发 MiniOB](docs/dev_by_gitpod.md)
4. [开发环境搭建(本地调试, 适用 Linux 和 Mac)](docs/how_to_dev_miniob_by_vscode.md)
5. [开发环境搭建(远程调试, 适用于 Window, Linux 和 Mac)](docs/how_to_dev_in_docker_container_by_vscode.md)
6. [miniob 词法语法解析开发与测试](docs/miniob-sql-parser.md)
6. [MiniOB 词法语法解析开发与测试](docs/miniob-sql-parser.md)
7. [doxygen 代码文档](docs/doxy/html/index.html)
或者直接看 [MiniOB GitHub Pages](https://oceanbase.github.io/miniob/).
更多的文档, 可以参考 docs 目录下的文档, 为了帮助大家更好的学习数据库基础知识, OceanBase 社区提供了一系列教程, 建议学习:
1. [《从0到1数据库内核实战教程》 视频教程](https://open.oceanbase.com/activities/4921877?id=4921946)
2. [《从0到1数据库内核实战教程》 基础讲义](https://github.com/oceanbase/kernel-quickstart)
3. [《数据库管理系统实现》 华中科技大学实现教材](docs/lectures/index.md)
3. [《数据库管理系统实现》 华中科技大学实现教材](docs/src/lectures/index.md)
## 系统架构
miniob 整体架构如下图所示:
![架构](docs/images/miniob-introduction-sql-flow.png)
MiniOB 整体架构如下图所示:
![架构](docs/src/images/miniob-introduction-sql-flow.png)
其中:
......@@ -62,11 +62,11 @@ OceanBase 初赛基于一套适合初学者实践的数据库实训平台 miniob
### 1. 大赛手把手入门教程
[大赛入门教程](https://github.com/oceanbase/kernel-quickstart/blob/V1.0.0/zh-CN/1.database-system-overview/5.miniob-github-gitee-instructions.md)
[大赛入门教程](docs/src/game/gitee-instructions.md)
### 2. 大赛赛题
[赛题介绍](docs/miniob_topics.md)
[赛题介绍](docs/src/game/miniob_topics.md)
### 3. 提交测试
......@@ -74,7 +74,7 @@ OceanBase 初赛基于一套适合初学者实践的数据库实训平台 miniob
在提交前, 请参考并学习 [训练营使用说明](https://ask.oceanbase.com/t/topic/35600372)
客户端输出需要满足一定要求,如果你的测试结果不符合预期,请参考 [miniob 输出约定](docs/miniob-output-convention.md)
客户端输出需要满足一定要求,如果你的测试结果不符合预期,请参考 [miniob 输出约定](docs/src/game/miniob-output-convention.md)
### 4. 大赛FAQ
......@@ -94,7 +94,7 @@ OceanBase 社区热情欢迎每一位对数据库技术热爱的开发者,期
## License
miniob 采用 [木兰宽松许可证,第2版](https://license.coscl.org.cn/MulanPSL2), 可以自由拷贝和使用源码, 当做修改或分发时, 请遵守 [木兰宽松许可证,第2版](https://license.coscl.org.cn/MulanPSL2).
MiniOB 采用 [木兰宽松许可证,第2版](https://license.coscl.org.cn/MulanPSL2), 可以自由拷贝和使用源码, 当做修改或分发时, 请遵守 [木兰宽松许可证,第2版](https://license.coscl.org.cn/MulanPSL2).
## 社区组织
......
[book]
language = "cn"
multilingual = false
src = "src"
title = "MiniOB"
[output.html]
git-repository-url = "https://github.com/oceanbase/miniob"
# Summary
- [MiniOB 简介](./miniob-introduction.md)
- [如何编译](./how_to_build.md)
- [开发环境搭建](./dev-env/introduction.md)
- [使用 GitPod 开发 MiniOB](./dev-env/dev_by_gitpod.md)
- [开发环境搭建(本地调试, 适用 Linux 和 Mac)](./dev-env/how_to_dev_miniob_by_vscode.md)
- [开发环境搭建(远程调试, 适用于 Window, Linux 和 Mac)](./dev-env/how_to_dev_in_docker_container_by_vscode.md)
- [Windows 使用Docker开发MiniOB](./dev-env/how_to_dev_miniob_by_docker_on_windows.md)
- [使用Docker开发MiniOB](./dev-env/how-to-dev-using-docker.md)
- [功能模块设计说明文档](./design/introduction.md)
- [事务](./design/miniob-transaction.md)
- [CLog](./design/miniob-clog.md)
- [SQL Parser](./design/miniob-sql-parser.md)
- [Doxy代码文档](./design/doxy/html/index.html)
- [OceanBase 数据库大赛](./game/introduction.md)
- [提交测试需要满足的输出要求](./game/miniob-output-convention.md)
- [2021届大赛题目介绍](./game/miniob_topics.md)
- [大赛手把手入门教程](./game/gitee-instructions.md)
- [数据库基础理论课程](./lectures/index.md)
- [第1章 数据库管理系统概述](./lectures/lecture-1.md)
- [第2章 数据库的存储结构](./lectures/lecture-2.md)
- [第3章 索引结构](./lectures/lecture-3.md)
- [第4章 查询处理](./lectures/lecture-4.md)
- [第5章 查询优化](./lectures/lecture-5.md)
- [第6章 事务处理](./lectures/lecture-6.md)
- [参考资料](./lectures/references.md)
- [版权声明](./lectures/copyright.md)
\ No newline at end of file
# 功能模块设计说明
- [事务](./miniob-transaction.md)
- [CLog](./miniob-clog.md)
- [SQL Parser](./miniob-sql-parser.md)
- [Doxy文档](./doxy/html/index.html)
\ No newline at end of file
......@@ -30,6 +30,8 @@ cmake -DCONCURRENCY=ON ..
```
然后在build目录执行 make。编译完成后启动 observer 服务端进程。
> 也可以使用 bash build.sh -DCONCURRENCY=ON 来编译
可以在启动observer时,增加 `-t mvcc` 选项来开启MVCC,假设当前目录是build(或build_debug之类):
```bash
......
# 搭建开发环境
MiniOB 当前可以在Linux/MacOS上编译,所以开发环境最好是Linux或者MacOS。Windows上可以使用WSL2,或者使用Docker。这里有几个文档,大家可以参考并选择自己的开发环境。另外,很多同学喜欢使用visual studio code开发,MiniOB 中也将vscode的一些配置文件放在了仓库中,比如 .vscode/tasks.json 和 .vscode/launch.json,可以参考使用。
- [使用 GitPod 开发 MiniOB](dev_by_gitpod.md)
- [开发环境搭建(本地调试, 适用 Linux 和 Mac)](how_to_dev_miniob_by_vscode.md)
- [开发环境搭建(远程调试, 适用于 Window, Linux 和 Mac)](how_to_dev_in_docker_container_by_vscode.md)
- [Windows 使用Docker开发MiniOB](how_to_dev_miniob_by_docker_on_windows.md)
- [使用Docker开发MiniOB](how-to-dev-using-docker.md)
\ No newline at end of file
# 1.4 MiniOB Gitee 使用说明
实战 MiniOB 编程需要在 Gitee 上创建自己的 private 仓库,在开发完成后,将代码提交到自己的仓库中,然后在训练营中进行测试。
MiniOB 仓库地址:<https://github.com/oceanbase/miniob>
训练营地址:<https://open.oceanbase.com/train>
本文将以 Gitee 为例介绍如何在训练营中进行提测以及常用的 Git 操作命令。
## Gitee 提测流程
前提条件:已注册 Gitee 账号,Gitee 官网地址:<https://gitee.com>
- 创建私有仓库
1. 登录 Gitee 平台,选择 **新建仓库**
![新建仓库](images/create-repo.png)
2. 输入仓库信息,单击 **创建**。设置为私有仓库后其他人无法查看到你的代码。
![新建仓库](images/create-repo2.png)
- 下载代码
```bash
# 将代码拉到本地
git clone https://github.com/oceanbase/miniob -b miniob_test
```
<main id="notice" type='explain'>
<h4>说明</h4>
<p>若网络状态不好,也可以直接在 GitHub 上下载代码压缩包,下载时需要先选择 miniob_test 分支。</p>
</main>
- 将 MiniOB 代码 push 到自己的仓库
```bash
# 进入到 miniob 目录,删除 .git 目录,清除已有的 git 信息
cd miniob
rm -rf .git
# 重新初始化 git 信息,并将代码提交到自己的仓库
git init
git add .
git commit -m 'init' # 提交所有代码到本地仓库
# 将代码推送到远程仓库
git remote add origin https://gitee.com/xxx/miniob.git # 注意替换命令中的 息为自己的库信息
git branch -M main
git push -u origin main
```
- 赋权官方测试账号
对于私有仓库,默认情况下其他人看不到,同样 OceanBase 测试后台也无法拉取到代码,这时想要提交测试,需要先给 OceanBase 的官方测试账号增加一个权限。
官方测试账号为:`oceanbase-ce-game-test`
首先在网页上打开自己的仓库,然后按照如下顺序操作即可。如果有疑问,也可以在 [OceanBase 社区论坛](https://ask.oceanbase.com/)或钉钉群(33254054)提问。
1. 选择 **管理 > 仓库成员管理 > 观察者**
![管理](images/reporter.png)
2. 选择 **直接添加**,搜索官方测试账号。
![邀请用户](images/invite-users.png)
3. 添加完成后,单击 **提交**
![添加成员](images/add-members.png)
## 日常 Git 开发命令
- 查看当前分支
```bash
git branch # 查看本地分支
git branch -a # 查看所有分支,包括远程分支
```
- 创建分支
```bash
git checkout -b 'your branch name'
git branch -d 'your branch name' # 删除一个分支
```
- 切换分支
```bash
git checkout 'branch name'
```
- 提交代码
```bash
# 添加想要提交的文件或文件夹
git add 'the files or directories you want to commit'
# 这一步也可以用 git add . 添加当前目录
# 提交到本地仓库
# -m 中是提交代码的消息,建议写有意义的信息,方便后面查找
git commit -m 'commit message'
```
- 推送代码到远程仓库
```bash
git push
# 可以将多次提交,一次性 push 到远程仓库
```
- 合并代码
```bash
# 假设当前处于分支 develop 下
git merge feature/update
# 会将 feature/update 分支的修改,merge 到 develop 分支
```
- 临时修改另一个分支的代码
```bash
# 有时候,正在开发一个新功能时,突然来了一个紧急 BUG,这时候需要切换到另一个分 去开发
# 这时可以先把当前的代码提交上去,然后切换分支。
# 或者也可以这样:
git stash # 将当前的修改保存起来
git checkout main # 切换到主分支,或者修复 BUG 的分支
git checkout -b fix/xxx # 创建一个新分支,用于修复问题
# 修改完成后,merge 到 main 分支
# 然后,继续我们的功能开发
git checkout feature/update # 假设我们最开始就是在这个分支上
git stash pop
# stash 还有很多好玩的功能,大家可以探索一下
```
# OceanBase 数据库大赛
2022 OceanBase 数据库大赛是由中国计算机学会(CCF)数据库专业委员会指导,OceanBase 与蚂蚁技术研究院学术合作团队联合举办的数据库内核实战赛事。本次大赛主要面向全国爱好数据库的高校学生,以“竞技、交流、成长”为宗旨,搭建基于赛事的技术交流平台,促进高校创新人才培养机制,不仅帮助学生从0开始系统化学习数据库理论知识,提升学生数据库实践能力,更能帮助学生走向企业积累经验,促进国内数据库人才的发展,碰撞出创新的火花。
更多详情, 请参考 [OceanBase 大赛](https://open.oceanbase.com/competition/index)
在开始参加大赛或者训练营之前,需要创建自己的代码仓库,这里有一个gitee的使用说明:
[大赛手把手入门教程](./gitee-instructions.md)
作为参考,这里有第一届数据库大赛的题目介绍:
[第一届数据库大赛题目介绍](./miniob_topics.md)
在参赛前,除了学习基础的理论知识,还可以使用OceanBase提供的训练营,来快速上手:
[训练营](https://open.oceanbase.com/train?questionId=200001)
训练营的使用方法比较简单,不过这里也有一个小手册:
[训练营使用手册](https://ask.oceanbase.com/t/topic/35600372)
注意,在训练营开始前,需要注意自己的程序输出需要满足一定的要求,请参考:
[提交测试需要满足的输出要求](./miniob-output-convention.md)
我们也收集了一些常见问题,可以参考:
[常见问题](https://ask.oceanbase.com/t/topic/35601465)