document

README.md

@@ -2,12 +2,34 @@
 
 本项目是 [CSDN 技能树](https://codechina.csdn.net/explore/topics/skill_tree) 的 PostgreSQL 专项。
 
-本仓库面向学习者，以树状结构管理 PostgreSQL 技能的知识点。
 
 为了操作方便，在仓库中有一组微型的 Python 工具脚本，用于加工和维护技能树，一般情况下不用关注。对于项目贡献者，
 主要维护的是技能树的目录结构和相关习题
 
 
+## 环境准备
+
+技能树仓库提供了辅助的工具脚本和 git hook 程序，在开始编辑工作之前，需要初始化环境依赖，我们推荐使用 python 3.8 或更高版本的 python。
+
+首先，请确认系统中已经安装 python 和 git，然后执行下列命令克隆仓库：
+
+```shell
+git clone git@codechina.csdn.net:csdn/skill_tree_java.git
+```
+
+然后进入 skill_tree_java 目录，执行下列命令安装依赖：
+
+```shell
+pip install -r requrirements.txt
+```
+
+然后执行下列命令安装钩子：
+
+```shell
+pre-commit install
+```
+
+
 ## 目录结构说明
 
 * 技能树`骨架文件`：
@@ -54,35 +76,15 @@
 
 通常情况下，我们只需要维护固定深度的目录结构，大部分知识点不涉及 children 的维护。
 
-## `知识节点` 的导出习题编辑
+## 习题编辑
 
-例如 `data/1.PostgreSQL初阶/7.查询数据/config.json` 里配置对该知识节点导出的习题
+编辑者需要关注两个重点问题
+- 根据需要编辑技能树的目录，每个目录应该由`序号.标题`组成，序号的数字不需要精确的保持连续，只要是整数即可，在提交
+  前执行 `python main.py`，该脚本会辅助整理目录序号
+- 在知识点的目录下编写习题，目前推荐使用 markdown 格式，我们仅就这个格式的习题编辑进行介绍
 
-```json
-{
-    "export": [
-        "hello.json"
-    ]
-}
-```
-
-每个文件名，指向对应的习题定义 json 。
-
-## `知识节点` 的导出习题选项配置编辑
-
-首先，我们添加前文中 export 指定的习题配置，例如在 `data/1.PostgreSQL初阶/7.查询数据` 下增加一个`hello.json`代码：
-
-```json
-{
-    "type": "code_options",
-    "author": "刘鑫",
-    "source": "hello.md",
-    "exercise_id":"1190bb7834904da0b1f20915960714d5",
-    "notebook_enable": false
-}
-```
-其中 type 字段目前都固定是 `code_options`。exercise_id 可以不写，处理程序会自动填补这个数据。notebook_enable对于 PG 技能树总是false。
-根据具体情况写好其它 字段，注意这里 source 的文件名，我们指定了一个 markdwon 文件。现在我们新建一个 HelloWorld.md 并编辑为：
+如前文内容，我们在知识节点下增加习题 `HelloWord`的定义文件，即在`data/1.Java初阶/1.Java概述/1.什么是Java`
+目录新建一个名为 `HelloWorld.md` 的文本文件，并编辑为：
 
 ````markdown
 # Hello World
@@ -124,9 +126,17 @@ log 'hello';
 
 ## 技能树合成
 
-在`src`目录下执行 `python main.py` 会合成技能树文件，合成的技能树文件: `data/tree.json`
-* 合成过程中，会自动检查每个目录下
-  * 是否有 `config.json`, 没有的话会新建一个 
-  * `config.json` 里的 `node_id` 是否存在，不存在则生成
-  * 目录序号是否连续，如果不连续会重排
-* 合成过程中，会自动检查每个知识点目录下 `config.json` 里的 `export` 里导出的习题配置，检查是否存在`exercise_id` 字段，如果不存在则生成
+## 技能树合成
+
+在`src`目录下执行 `python main.py` 会合成技能树文件，合成的技能树文件为: `data/tree.json`
+* 合成过程中，会检查章节目录下是否有 `config.json` 文件，如果没有，会自动生成，需要注意的是，这时 config.json是不完 
+  整的，没有 keywords 信息
+* 每个知识点目录（即技能树最末端的叶子节点）的 config.json ，需要设定关键字，如果 `config.json` 的 keywords 为空，执行
+  main.py 会提示错误并中途退出，执行`git commit`时，commit 钩子也会拒绝提交
+* 合成过程中，会自动检查每个目录下 `config.json` 里的 `node_id` 是否存在，不存在则生成
+* 合成过程中，会修复目录的序号，保持每一个章节目录的子目录总是从 1 开始的整数序列
+* 合成过程中，会自动检查每个知识点目录下的 markdown 文件，是否有对应的配置信息，如果不存在则生成
+    * 生成的习题配置信息中，author是根据git环境信息填写的，如果这个作者名不是您的csdn账户名，您可以手工编辑修改
+    * config.json 的 export 字段定义了同一个知识点下习题的顺序，如果需要定义不同的顺序，您可以手工调整
+    * 技能树仓库钩子和辅助工具都会检查信息完整性，并尝试做必要的修补，因此可能在提交时发现有一些新文件
+      生成，请在后续的提交中将它们也发送到服务器仓库