From d51ebe91a4e436bc4e54d859f4355c2a0adf2e1d Mon Sep 17 00:00:00 2001 From: "TOKISAKIX\\21168" <2116884726@qq.com> Date: Wed, 13 Dec 2023 15:27:00 +0800 Subject: [PATCH] add mkdocs --- README.md | 47 ++++--------------- docs/.gitignore | 1 + {asset => docs/docs/asset}/devcontainer1.png | Bin {asset => docs/docs/asset}/devcontainer2.png | Bin {asset => docs/docs/asset}/devcontainer3.png | Bin {asset => docs/docs/asset}/z710.jpg | Bin docs/{ => docs}/board.md | 2 +- docs/{env_doc.md => docs/env.md} | 6 +-- docs/docs/index.md | 30 ++++++++++++ docs/mkdocs.yml | 11 +++++ docs/requirements.txt | 5 ++ 11 files changed, 61 insertions(+), 41 deletions(-) create mode 100644 docs/.gitignore rename {asset => docs/docs/asset}/devcontainer1.png (100%) rename {asset => docs/docs/asset}/devcontainer2.png (100%) rename {asset => docs/docs/asset}/devcontainer3.png (100%) rename {asset => docs/docs/asset}/z710.jpg (100%) rename docs/{ => docs}/board.md (98%) rename docs/{env_doc.md => docs/env.md} (95%) create mode 100644 docs/docs/index.md create mode 100644 docs/mkdocs.yml create mode 100644 docs/requirements.txt diff --git a/README.md b/README.md index 306e94d..1da20ff 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,17 @@ # YatCPU -本仓库由 [Tokisakix](https://github.com/Tokisakix)、[PurplePower](https://github.com/PurplePower)、[Han Huang](https://github.com/HHTheBest) 在 [2022-fall-yatcpu-repo](https://github.com/hrpccs/2022-fall-yatcpu-repo) 的基础上结合 2023 机组教学实情整理而来，有较多原创内容 +本仓库由 [Tokisakix](https://github.com/Tokisakix)、[PurplePower](https://github.com/PurplePower)、[Han Huang](https://github.com/HHTheBest) 在 [2022-fall-yatcpu-repo](https://github.com/hrpccs/2022-fall-yatcpu-repo) 的基础上结合 2023 计组教学实情整理而来，有较多原创内容 (PS: 能求个 star⭐ 吗 QAQ ~) -- [YatCPU](#yatcpu) - * [为什么创建本仓库](#jmp1) - * [本仓库的优势](#jmp2) - * [如何使用本整合仓库](#jmp3) - + [如何一键完成环境配置](#jmp31) - + [如何使用一键烧板脚本](#jmp32) - * [外部参考链接](#jmp4) +## Getting Started -## 为什么创建本仓库？ +你可以选择在线阅读我们编写的[配套文档](http://www.tokisakix.cn/2023-Fall-YatCPU-Docs/) -1. 开发环境配置困难，为配置开发环境需要付出很多精力，开发效率低 -2. 学生在运行 build.bat 或 build.sh 时经常遇到问题 -3. 原教学仓库 [2022-fall-yatcpu-repo](https://github.com/hrpccs/2022-fall-yatcpu-repo) 并不支持 ZYBO-Z710 开发板的烧录 -4. ZYBO-Z710 烧板流程复杂、为支持烧板脚本的正常运行需要学生手动根据助教增改很多文件，开发效率低 - -## 本整合仓库具有以下特点： - -- 提供基于 Vscode + Dev Container 一键环境配置工具和配套文档 -- 已提前用 cmake 编译好测试文件，无须再运行 build.bat 或 build.sh -- 完全保留了原教学仓库的代码段填空设置和项目架构，代码迁移便利 -- 支持 Basys3、Pynq、Verilator、ZYBO-Z710 四款开发板的一键烧录，学生可以专心把精力集中在 CPU 的编写 - -## 如何使用本整合仓库？ - -下列内容主要讲述如何使用本仓库来完成开发环境的一键配置和一键烧板 - -### 如何使用一键完成环境配置 - -[点击此处跳转页面](docs/env_doc.md) - -### 如何使用一键烧板脚本 - -[点击此处跳转页面](docs/board.md) - -## 外部参考链接 -- [YatCPU 文档地址](https://yatcpu.sysu.tech) -- [YatCPU 的 Dev Container 环境配置](http://tokisakix.cn/2023/11/14/%5BDocker%5D%20YatCPU%20%E7%9A%84%20Dev%20container%20%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE/) -- [测试 Tokisakix 的烧板文件](https://blog.skyw.cc/archives/258.html) +你也可以选择在下载到本地后阅读 +``` +git clone https://github.com/Tokisakix/2023-fall-yatcpu-repo.git +cd 2023-fall-yatcpu-repo/docs +pip install -r requirements.txt +mkdocs serve +``` \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..d97e100 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +site \ No newline at end of file diff --git a/asset/devcontainer1.png b/docs/docs/asset/devcontainer1.png similarity index 100% rename from asset/devcontainer1.png rename to docs/docs/asset/devcontainer1.png diff --git a/asset/devcontainer2.png b/docs/docs/asset/devcontainer2.png similarity index 100% rename from asset/devcontainer2.png rename to docs/docs/asset/devcontainer2.png diff --git a/asset/devcontainer3.png b/docs/docs/asset/devcontainer3.png similarity index 100% rename from asset/devcontainer3.png rename to docs/docs/asset/devcontainer3.png diff --git a/asset/z710.jpg b/docs/docs/asset/z710.jpg similarity index 100% rename from asset/z710.jpg rename to docs/docs/asset/z710.jpg diff --git a/docs/board.md b/docs/docs/board.md similarity index 98% rename from docs/board.md rename to docs/docs/board.md index aa0c256..d7f168a 100644 --- a/docs/board.md +++ b/docs/docs/board.md @@ -39,6 +39,6 @@ cd vivado/z710 **如果烧板无误，你会看到黄灯亮起** -![image](/asset/z710.jpg) +![image](asset/z710.jpg) 后续将上述 program_device.tcl 换成 generate_and_program.tcl 可以将生成比特流和烧板在一个脚本中完成。 \ No newline at end of file diff --git a/docs/env_doc.md b/docs/docs/env.md similarity index 95% rename from docs/env_doc.md rename to docs/docs/env.md index 30772b0..32b6a9f 100644 --- a/docs/env_doc.md +++ b/docs/docs/env.md @@ -17,7 +17,7 @@ 在 VSCode 的扩展处搜索 Dev Containers，下载安装 -![image](/asset/devcontainer1.png) +![image](asset/devcontainer1.png) **使用 Dev Containers 打开项目** @@ -25,7 +25,7 @@ 在上方的运行选项中选择在容器中重新打开，这个命令会让 Dev container 自动根据 devcontainer.json 里的配置信息来创建 Docker 环境 -![image](/asset/devcontainer2.png) +![image](asset/devcontainer2.png) 如果你是第一次在容器中打开，你可能需要十几分钟的时间等待容器配置完毕，如果在配置过程中发生异常，请检查你的网络情况后再次运行 @@ -35,7 +35,7 @@ 新建终端输入 sbt test，期望你有如下输出 -![image](/asset/devcontainer3.png) +![image](asset/devcontainer3.png) ```bash [info] All tests passed. diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..234f8e5 --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,30 @@ +本仓库由 [Tokisakix](https://github.com/Tokisakix)、[PurplePower](https://github.com/PurplePower)、[Han Huang](https://github.com/HHTheBest) 在 [2022-fall-yatcpu-repo](https://github.com/hrpccs/2022-fall-yatcpu-repo) 的基础上结合 2023 计组教学实情整理而来，有较多原创内容 + +(PS: 能求个 star⭐ 吗 QAQ ~) + +## 为什么创建本仓库？ + +1. 开发环境配置困难，为配置开发环境需要付出很多精力，开发效率低 +2. 学生在运行 build.bat 或 build.sh 时经常遇到问题 +3. 原教学仓库 [2022-fall-yatcpu-repo](https://github.com/hrpccs/2022-fall-yatcpu-repo) 并不支持 ZYBO-Z710 开发板的烧录 +4. ZYBO-Z710 烧板流程复杂、为支持烧板脚本的正常运行需要学生手动根据助教增改很多文件，开发效率低 + +## 本仓库具有的优势 + +- 提供基于 Vscode + Dev Container 一键环境配置工具和配套文档 +- 已提前用 cmake 编译好测试文件，无须再运行 build.bat 或 build.sh +- 完全保留了原教学仓库的代码段填空设置和项目架构，代码迁移便利 +- 支持 Basys3、Pynq、Verilator、ZYBO-Z710 四款开发板的一键烧录，学生可以专心把精力集中在 CPU 的编写 + +## 如何使用本整合仓库？ + +下列内容主要讲述如何使用本仓库来完成开发环境的一键配置和一键烧板 + +1. [如何使用一键完成环境配置](env.md) +2. [如何使用一键烧板脚本](board.md) + +## 外部参考链接 + +- [YatCPU 文档地址](https://yatcpu.sysu.tech) +- [YatCPU 的 Dev Container 环境配置](http://tokisakix.cn/2023/11/14/%5BDocker%5D%20YatCPU%20%E7%9A%84%20Dev%20container%20%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE/) +- [测试 Tokisakix 的烧板文件](https://blog.skyw.cc/archives/258.html) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..e27ed89 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,11 @@ +site_name: 2023-Yatcpu-Fall-Docs +site_author: Tokisakix +copyright: Copyright © 2023 Tokisakix + +nav: +- 主页: index.md +- 如何一键环境配置: env.md +- 如何一键烧板: board.md + +theme: + name: material \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..86de9ec --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +mkdocs +mkdocs-material +mkdocs-material-extensions +mkdocs-git-revision-date-localized-plugin==0.9.2 +mkdocs-git-authors-plugin==0.3.3 \ No newline at end of file