diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 000000000..1d2cefd69 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,32 @@ +name: Deploy MkDocs + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - name: Check out the repo + uses: actions/checkout@main + + - name: Setup Python + uses: actions/setup-python@main + with: + python-version: '3.x' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material + + - name: Update dir + run: python ./update_dir.py + + - name: Deploy docs to GitHub Pages + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index d68a35969..5f7c775ea 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,27 @@ -![avatar](https://raw.githubusercontent.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/main/image/cqut_logo.png) +![avatar](https://cdn.jsdmirror.com/gh/Royfor12/CQUT-Course-Guide-Sharing-Scheme/image/cqut_logo.png) # 💡 课程攻略共享计划 -[![](https://img.shields.io/github/watchers/Royfor12/CQUT-electronic-information-engineering.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/watchers) -[![](https://img.shields.io/github/stars/Royfor12/CQUT-electronic-information-engineering.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/stargazers) -[![](https://img.shields.io/github/forks/Royfor12/CQUT-electronic-information-engineering.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/network/members) -[![](https://img.shields.io/github/issues-pr-closed-raw/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-electronic-information-engineering/issues) +[![](https://img.shields.io/github/watchers/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/watchers) +[![](https://img.shields.io/github/stars/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/stargazers) +[![](https://img.shields.io/github/forks/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/forks) +[![](https://img.shields.io/github/issues-pr-closed-raw/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/pulls) ![](https://img.shields.io/github/repo-size/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat) -![Platform](https://img.shields.io/badge/platform-windows%20|%20linux%20|%20macos-green.svg) +[![jsdelivr](https://img.shields.io/badge/CDN-jsdelivr-brightgreen?logo=jsdelivr&logoSize=auto)](https://www.jsdelivr.com/) ## ❗ 写在最前 -如果你打开本网页不知如何操作或检索所需的资源，请先点击[GitHub使用指南](https://www.bilibili.com/video/BV1hS4y1S7wL)。 +如果你打开本网页不知如何操作或检索所需的资源，请先点击[GitHub使用指南](https://www.bilibili.com/video/BV1hS4y1S7wL)。 旧版备份[2025/1/7](https://pan.baidu.com/s/1_YFOqR_eSd8bXokEGMCrbg?pwd=hq33)提取码：hq33 ## ⚡ 前言 -网络冲浪🏄时发现了：浙江大学的课程攻略共享计划与上海交通大学生存手册，深受震撼。\ +网络冲浪🏄时发现了：浙江大学的课程攻略共享计划与上海交通大学生存手册，深受震撼。 故此也想建立一个重庆理工大学课程攻略计划，本仓库的内容包括重庆理工大学的各类课程复习资料。本仓库为非营利、永久免费的开源项目，仓库之目的即推动知识传播、提高资源质量、减少获取成本、提倡无纸化资料、促进教育公平，让西唯兵学子在备考、复习之时不必再苦寻资料。 -我们同在重庆理工大学，以相同的身份，学习相同的课程，师从相同的教授。教授们往往为了省事，所以几年的课程资料、期末试题可能变化不大。学习这些资料，阅读学长学姐留下的复习攻略，可能会减轻信息不对称对你造成的影响，让你在复习时更有针对性。面对年复一年、无数学子独立摸索、重复劳动的现状，我不禁感到惋惜与不平。\ -再加之本人有数字仓鼠🐹症。 -因此，我希望建立一个项目，将这些隐匿的、不确定性的、口耳相传的知识资源整合起来，使之变得公开透明、易于获取，并且能够由大家共同维护、持续丰富。 +我们同在重庆理工大学，以相同的身份，学习相同的课程，师从相同的教授。教授们往往为了省事，所以几年的课程资料、期末试题可能变化不大。学习这些资料，阅读学长学姐留下的复习攻略，可能会减轻信息不对称对你造成的影响，让你在复习时更有针对性。面对年复一年、无数学子独立摸索、重复劳动的现状，我不禁感到惋惜与不平。 +再加之本人有数字仓鼠🐹症。 +因此，我希望建立一个项目，将这些隐匿的、不确定性的、口耳相传的知识资源整合起来，使之变得公开透明、易于获取，并且能够由大家共同维护、持续丰富。 借用浙大的课程攻略中的一句话：**我希望只要是前人走过的弯路，后人就不必再走。这是我的信念，也是我建立这个项目的原因。** ## 📣 特性 @@ -39,6 +39,12 @@ 目前涵盖的科目还很少，欢迎各位前来PR！ +### 🎉 新界面 + +本仓库已实现 GitHub Actions 工作流全自动部署。 +在 Push 或 PR 后会触发自动构建新的静态网页并部署到 **https://Royfor12.github.io/CQUT-Course-Guide-Sharing-Scheme** 。 +该网页界面友好，在左侧导航栏中可以查找并单独下载指定文件。 + ## 🦧 平台 以下摘录自浙江大学课程攻略共享计划 @@ -51,10 +57,9 @@ ## ⏬ 下载 -我们在这里介绍两种下载文件的方式： - 1. 你当然可以克隆或者下载整个项目，但因为整个项目较大，可能对于一部分人不太方便。这里对于使用Chrome和Firefox的用户，我们推荐一个[Chrome插件](https://chrome.google.com/webstore/detail/gitzip-for-github/ffabmkklhbepgcgfonabamgnfafbdlkn?hl=en)和[Firefox插件](https://addons.mozilla.org/en-US/firefox/addon/gitzip/)，**GitZip**。该插件可以让我们只下载项目中我们感兴趣的那些文件夹，也就是我们所感兴趣的课程的资料。同时对Opera用户来说，大部分的Chrome插件都可以通过一款名为[Install Chrome Extensions](https://addons.opera.com/zh-cn/extensions/details/install-chrome-extensions/)的Opera插件安装使用，GitZip也不例外。而对于使用其他浏览器的朋友来说，很遗憾，这个插件暂时只能在这三款浏览器中使用。 -2. 或者复制该文件夹的网址，粘贴入[DownGit](https://minhaskamal.github.io/DownGit/#/home)中，选择**download**即可。 +2. 或者复制想要打包下载文件夹的网址，粘贴入[DownGit](https://minhaskamal.github.io/DownGit/#/home)中，选择**download**即可。 +3. 访问 **https://Royfor12.github.io/CQUT-Course-Guide-Sharing-Scheme** 。文件下载加速CDN由 [![jsdelivr](https://img.shields.io/badge/CDN-jsdelivr-brightgreen?logo=jsdelivr&logoSize=auto)](https://www.jsdelivr.com/) 及其镜像站提供。 注：对于第一种方法而言，它需要使用者拥有github账号，并且该插件需要使用者的授权；而第二种方法虽然一次只能下载一个文件夹，但它并不需要使用者拥有github账号。 @@ -166,7 +171,7 @@ Issue、PR、纠错、补充、上传攻略，完全欢迎！ ## 📔待办事项 - [ ] 制定使用指南 -- [ ] 设计一个网页便于检索与预览 +- [x] 设计一个网页便于检索与预览 ## 🍻赞助 Buy me coffee. @@ -179,4 +184,4 @@ Buy me coffee. ## ✨Stars -[![Star History Chart](https://api.star-history.com/svg?repos=Royfor12/CQUT-Course-Guide-Sharing-Scheme&type=Date)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme&Date) +[![Star History Chart](https://api.star-history.com/svg?repos=Royfor12/CQUT-Course-Guide-Sharing-Scheme&type=Date)](https://star-history.com/#Royfor12/CQUT-Course-Guide-Sharing-Scheme&Date) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..b2edde69c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,42 @@ +site_name: 重庆理工大学课程攻略共享计划 +site_author: H·Sofie, Royfor12 +site_description: 使用MKDocs构建的静态网页 +site_url: https://Royfor12.github.io/CQUT-Course-Guide-Sharing-Scheme +repo_url: https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme + +theme: + name: material + language: zh + font: + text: Noto Sans Simplified Chinese + features: + - navigation.instant # 即时加载 + - navigation.instant.prefetch # 即时预取 + - navigation.instant.progress # 加载进度指示器 + - navigation.instant.preview # 即时预览 + - navigation.sections # 导航栏分组 + - navigation.path # 标题导航路径 + - navigation.top # 返回顶部按钮 + - toc.follow # 目录锚点跟随 + - search.highlight # 搜索高亮显示 + - content.footnote.tooltips # 脚注内联 + +plugins: + - search: + lang: zh + +markdown_extensions: + - abbr + - admonition + - pymdownx.details + - attr_list + - def_list + - footnotes + - md_in_html + - tables + - pymdownx.betterem + - pymdownx.caret + - pymdownx.mark + - pymdownx.tilde + - pymdownx.tasklist: + custom_checkbox: true diff --git a/update_dir.py b/update_dir.py new file mode 100644 index 000000000..8dc6dde7d --- /dev/null +++ b/update_dir.py @@ -0,0 +1,112 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- + +import os +import shutil +from urllib.parse import quote + +# 从 GitHub Actions 环境变量里获取仓库所有者和仓库名、分支名 +repo_full = os.environ.get("GITHUB_REPOSITORY", "defaultOwner/defaultRepo") +branch = os.environ.get("GITHUB_REF_NAME", "main") + +# 文本文件走 blob 链接（在线查看），二进制文件走 cdn 链接（便于直接下载） +BLOB_URL_PREFIX = f"https://github.com/{repo_full}/blob/{branch}/" +BIN_URL_PREFIX = f"https://cdn.jsdmirror.com/gh/{repo_full}/" + +# 顶层排除目录 +EXCLUDE_TOP_DIRS = {'.git', 'docs', '.vscode', '.circleci', 'site', 'image'} + +# 视为 README 的文件名 +README_CANDIDATES = {'README.md', 'readme.md', 'index.md'} + +# 生成 blob 链接 +BLOB_EXTS = {'md', 'txt', 'c', 'cpp', 'py'} + +def process_directory(base_dir: str, rel_path: str): + """ + 将 base_dir(绝对路径) 对应的目录内容，递归生成到 docs/rel_path 目录下的 index.md 中。 + 1. 若有 README_CANDIDATES 中任意文件，则将其内容原样写入。 + 2. 新起一行后，输出大标题 "# 文件列表"。 + 3. 列出当前目录所有文件的链接（md/txt -> blob，其它 -> cdn）。 + 4. 对各子文件夹，递归调用 process_directory，生成各自的 docs/rel_path/subfolder/index.md。 + """ + + # 在 docs/ 下创建与原目录相同层级的文件夹 + docs_folder = os.path.join("docs", rel_path) + if not os.path.exists(docs_folder): + os.makedirs(docs_folder) + + items = sorted(os.listdir(base_dir)) + + # 尝试找到任意一个 README + readme_content = "" + for candidate in README_CANDIDATES: + if candidate in items: + readme_path = os.path.join(base_dir, candidate) + with open(readme_path, "r", encoding="utf-8") as rf: + readme_content = rf.read() + break # 找到一个就可以退出 + + # 收集文件链接列表 + file_links = [] + subdirs = [] + for item in items: + full_item_path = os.path.join(base_dir, item) + if os.path.isfile(full_item_path): + # 若是 README，则已处理过；否则纳入链接 + if item not in README_CANDIDATES: + ext = item.split(".")[-1].lower() if "." in item else "" + # 判断用 blob 还是 cdn 加速 + if ext in BLOB_EXTS: + file_url = BLOB_URL_PREFIX + quote(f"{rel_path}/{item}") + else: + file_url = BIN_URL_PREFIX + quote(f"{rel_path}/{item}") + file_links.append((item, file_url)) + else: + # 是子目录 + subdirs.append(item) + + # 写出当前目录的 index.md + index_md_path = os.path.join(docs_folder, "index.md") + with open(index_md_path, "w", encoding="utf-8") as wf: + # 1) 写 README 内容（若有） + if readme_content.strip(): + wf.write(readme_content.strip()) + wf.write("\n\n---\n\n") # 加点空行，避免直接跟标题混在一起 + + # 2) 输出大标题“# 文件列表” + wf.write("# 文件列表\n") + + # 3) 列出当前目录内的文件链接 + for fname, url in file_links: + wf.write(f"- [{fname}]({url})\n") + wf.write("\n") + + # 4) 递归处理子目录 + for subdir in subdirs: + sub_rel_path = os.path.join(rel_path, subdir) + full_subdir_path = os.path.join(base_dir, subdir) + process_directory(full_subdir_path, sub_rel_path) + + +if __name__ == "__main__": + + # 确保 docs 目录存在 + if not os.path.exists("docs"): + os.mkdir("docs") + + # 排除 EXCLUDE_TOP_DIRS + top_dirs = [] + for d in sorted(os.listdir(".")): + if os.path.isdir(d) and d not in EXCLUDE_TOP_DIRS: + top_dirs.append(d) + + for d in top_dirs: + # 绝对路径 + abs_path = os.path.abspath(d) + # rel_path 就是顶层目录的名字 d + process_directory(abs_path, d) + + # 若仓库根目录下存在 README.md，则复制到 docs/index.md 当主页 + if os.path.exists("README.md"): + shutil.copyfile("README.md", "docs/index.md")