{"id":20418659,"url":"https://github.com/wklchris/blog","last_synced_at":"2025-04-12T17:35:25.098Z","repository":{"id":155691748,"uuid":"420847679","full_name":"wklchris/blog","owner":"wklchris","description":"个人 Github.io 站点上的博客文章 | Blogs on my Github.io site","archived":false,"fork":false,"pushed_at":"2025-04-12T10:14:09.000Z","size":7346,"stargazers_count":32,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T11:26:39.237Z","etag":null,"topics":["blog","restructuredtext"],"latest_commit_sha":null,"homepage":"https://wklchris.github.io/blog","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wklchris.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-25T02:02:50.000Z","updated_at":"2025-02-12T08:11:11.000Z","dependencies_parsed_at":"2024-11-21T03:31:54.353Z","dependency_job_id":null,"html_url":"https://github.com/wklchris/blog","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wklchris%2Fblog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wklchris%2Fblog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wklchris%2Fblog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wklchris%2Fblog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wklchris","download_url":"https://codeload.github.com/wklchris/blog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248606039,"owners_count":21132290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blog","restructuredtext"],"created_at":"2024-11-15T06:34:10.827Z","updated_at":"2025-04-12T17:35:25.074Z","avatar_url":"https://github.com/wklchris.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blog 博文 \u003c!-- omit in TOC --\u003e\n\n这时我个人 Github Page ([wklchris.github.io](wklchris.github.io)) 页面的博文仓库。 \n\n下文将介绍如何使用该仓库中的工具或模板：\n- [依赖项](#依赖项)\n- [模板结构](#模板结构)\n- [make.py 工具](#makepy-工具)\n  - [创建新文档](#创建新文档)\n  - [构建文档](#构建文档)\n  - [移除文档](#移除文档)\n  - [本地预览](#本地预览)\n- [ju.ps1 脚本](#jups1-脚本)\n- [其他注意事项：nojekyll](#其他注意事项nojekyll)\n- [许可证](#许可证)\n\n\n## 依赖项\n\n本站使用网页文档构建工具 [Sphinx](https://www.sphinx-doc.org/) 构建。要使用本站模板，请先安装 Python (\u003e=3.6)，并安装以下库：\n\n- sphinx\n- sphinx-rtd-theme\n- sphinx-copybutton\n\n可以使用 `Python` 自带的 `pip` 工具进行安装，命令行如下，\n```powershell\npip install sphinx sphinx-rtd-theme nbsphinx sphinx-copybutton\n```\n\n本仓库的开发环境是 Windows 10，并未在其他环境下测试。已知的 macOS/Linux 不兼容有：\n- `make.py`：`--server` 参数调用了 Powershell 来打开网页文件。\n\n## 模板结构\n\n本仓库的 Github Pages 功能定位于 master 分支的 `docs/` 文件夹，这可以在 Github 仓库的设置中进行配置。\n\n\u003e 读者如果要使用本站的模板，请保留以下列出的所有关键文件，并用 `make.py` 文件来管理博文。\n\n关键文件：\n- `make.py`：原 `make.bat` / `Makefile` 的优化替代。\n- `ju.ps1`：一个快速以文档文件夹为工作目录启动 Jupyter Notebook 的脚本。\n- `docs\\`\n  - `_config\\`：全局文件。\n    - `db.json`：全站的文档 meta 数据。\n    - `hyperconf.json`，`index.html`，`index.rst`：用于初始化文档仓库的文件。\n    - `index-homepage.rst`：用于更新主页的模板文件。\n  - `.nojekyll`：阻止 Github Pages 的 Jekyll 功能。\n- `docsrc\\`\n  - `_homepage\\`: 主网站页面的源文件夹。\n    - `404.rst`：网站内的 404 错误提示页。\n    - `conf.py`：屏蔽了 homepage 的 template，准备稍加自定义。\n  - `_static\\`：样式文件。\n    - `homepage_style.css`：专为 homepage 定制的 CSS 文件。\n    - `style.css`：普通博文的 CSS 文件。\n  - `_templates\\layout.html`\n    - 配置了侧边栏的“返回主页”按钮。\n    - 配置了 Google Analytics。\n\n网站的主页使用了 DataTables 来呈现博文列表，其路径在 `docs/_config/static/DataTables`。值得注意的是，由于 `requirejs` 的存在，`DataTables` 必须以一种不同于官网的形式调用（见 `docsrc/_templates/layout.html` 中的 `require.config()` 部分）——尽管只有主页需要它，但目前它会在所有页面上都被加载。\n\n使用 `make.py` 初始化的 `index.rst` 文件均带有文档头，用于记录文档的数据并存储在 `config/db.json` 中。例如：\n```rst\n.. meta::\n   :category: Python\n   :keywords: python,matplotlib,plot,computing\n   :series: Python-libs\n   :series_num: 1\n   :abstract: 本文介绍了 Python 最广为使用的科学绘图库 Matplotlib\n```\n\n各个键的功能仍在开发中，目前的设想有：\n- [x] category：主页的博文列表按照 category 进行分类。\n- [ ] keywords\n- [ ] series：同 series 的博文互相推荐，并引导读者按序阅读。\n- [x] abstract：主页的博文列表中展示文章摘要。\n\n\n## make.py 工具\n\n仓库中的 `make.py` 是本人编写的文档快速管理工具，用法是：\n\n```powershell\npython make.py [-h] \n    [--build | --create | --remove | --server]\n    [--title TITLE [TITLE ...]]\n    [--no-update-homepage]\n    docname\n```\n\n对于 Windows 用户，如果在 `PATH_EXT` 环境变量中加上对 `;.py` 的执行支持，并将 `.py` 文件的默认打开方式设置为了 Python 解释器，那么可以省略最前面的 `python` 前缀；在下述内容中，该前缀默认省略。\n\n各参数：\n- `-h`：显示帮助。\n- 互斥参数组：以下三个参数最多只能同时传入1个。\n  - `--build` / `-b`：（默认）网页构建模式。\n  - `--create` / `-c`：创建模式。\n    - `--title` / `-t`：指定文档一个与项目名称不同的标题。仅在创建模式生效。\n  - `--remove` / `-R`：删除模式。\n  - `--server` / `-s`：本地服务器模式。\n- `--no-update-homepage` / `-N`：在构建或删除文档时，不自动更新全站主页。仅在构建或删除模式生效。\n- `docname`：必选参数。文档项目名称，同时也是文档文件夹的名称。\n\n以下样例均在 Windows 10，**Powershell 环境**中执行。请注意，在 CMD 中的表现很可能不同。\n\n### 创建新文档\n\n用 `--create/-c` 参数创建一个名为 `doc1` 的文档，路径在 `docsrc/doc1`。它会被自动初始化，加入 `index.rst`，`index.html` 与 `conf.py`。\n\n```powershell\n./make.py -c doc1\n```\n\n文档内标题默认与项目名相同。如果要指定一个文档内标题，使用 `--title/-t` 参数来配合 `--create/-c` 参数：\n\n```powershell\n./make.py -c doc1 -t Long title with spaces\n```\n\n特别地，`-t` 参数允许带空格；上例的 `doc1` 文档标题即为 `Long title with spaces`。\n\n### 构建文档\n\n使用 `--build/-b` 参数（或者省略）来构建文档，将其转为 HTML。构建后的 HTML 会临时生成在 `docsrc/doc1/build` 文件夹中，随后 `docsrc/doc1/build/html` 中的所有文件会被移动到 `docs/doc1` 中，然后临时文件夹 `build` 会被删除。\n\n```powershell\n./make.py doc1\n```\n\n同时，该命令还会尝试自动更新数据库 `db.json`，并自动构建主页（从 `docsrc/_hompage` 到 `docs/`）。因此用户会在控制台中观察到两次 sphinx 构建。如果用户不想自动构建主页，可以添加 `--no-update-homepage/-N` 参数：\n\n```powershell\n./make.py -N doc1\n```\n\n* 如果要单独构建主页，请使用 `-N` 参数： `./make.py -N _homepage`\n\n### 移除文档\n\n使用 `--remove/-R` 参数来移除指定的文档。\n\n```powershell\n./make.py -R doc1\n```\n\n该文档的所有记录均会被删除，包括：\n- 源文件：移除整个 `docsrc/doc1` 文件夹；\n- 数据库记录：移除 `db.json` 中所有关于文档 `doc1` 的记录项；\n- 主页的文档列表：（如果未使用 `--no-update-homepage/-N` 参数）在更新数据库后，主页会自动重编译，以保证 `doc1` 已经从列表中被移除。\n\n### 本地预览\n\n\u003e 部分线上功能必须通过 HTTP 服务才能测试（请记得按 Ctrl + F5 刷新页面缓存），仅仅在本地双击打开 HTML 文件是不行的。\n\n使用 `--server/-s` 参数来在 `docs/` 文件夹搭建本地 HTTP 服务（默认 `http://localhost:8000`），并自动使用浏览器打开 `doc1` 项目的 HTML 主页：\n\n```powershell\n./make.py -s doc1\n```\n\n按 Enter 键（推荐），或者按 Ctrl + C 强制打断，即可中止该本地服务器。注意，在浏览器打开的选项卡过多时，中止操作可能会变得不灵敏。\n\n\n## ju.ps1 脚本\n\n该脚本帮助用户迅速以给定文档名所在的目录为工作目录，打开 Jupyter Notebook 服务。例如，下面的命令会以 `docsrc/Python/` 为工作目录运行 Jupyter Notebook 服务： \n\n```powershell\n./ju.ps1 Python\n```\n\n## 其他注意事项：nojekyll\n\n本仓库是作为个人 github.io 域名的次级域名启用的，Github Pages 服务的运行根目录需要在仓库的设置中设置为 `docs/` 目录。\n\n特别注意，此种情形下，`.nojekyll` 文件应该放在 `docs/` 目录下，而不是根目录中。否则会引起无法加载 CSS 等文件的问题。\n\n\n## 许可证\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwklchris%2Fblog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwklchris%2Fblog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwklchris%2Fblog/lists"}