[IntelliJ IDEA + EduTools] 从零开始编写一套 Java 教材（二）

目录

[IntelliJ IDEA + EduTools] 从零开始编写一套 Java 教材（零）

[IntelliJ IDEA + EduTools] 从零开始编写一套 Java 教材（一）

上期回顾

第二课　YAML in EduTools

第0节　YAML 语言的介绍

第1节　Course-info.yaml（课程配置）

第2节　section-info.yaml（章节配置）

第3节　lesson-info.yaml（课时配置）

第4节　task-info.yaml（任务配置）

下集预告

[IntelliJ IDEA + EduTools] 从零开始编写一套 Java 教材（三）

---

上期回顾

在上一课中，我们详细地讲解了如何为 IntelliJ IDEA Ultimate 安装 EduTools 插件、为教程项目配置 JDK 与 Gradle ，同时成功地创建了一个基于 Gradle 的 Java 教程项目并导入至 IntelliJ IDEA 中。

一本优秀的教材通常都会将知识点分门别类、集中整合，方便师生共同学习。EduTools 将一个课程项目分成了4个层次：

1. 课程整体（Course），使用 course-info.yaml 进行配置
2. 各章节（Section），使用 section-info.yaml 进行配置
3. 课时（Lesson），使用 lesson-info.yaml 进行配置
4. 任务（Task），使用 task-info.yaml 进行配置

在这一课中，我们将介绍这4种 YAML 文件的格式并教大家如何读懂它。

---

第二课　YAML in EduTools

 

第0节　YAML 语言的介绍

YAML (Yet Another Markup Language) 是一种与 XML / JSON 类似的、专用于编写配置文件的标记性语言，它能够使用比 JSON 更为简单的方式编写任意规模的配置文件。这是一种格式严格的标记语言，它使用空白字符（White Space）缩进来展示配置之间的层次关系。

YAML 为我们提供了3种数据结构：对象（键-值对）、数组和字面常量，我们借助它们的嵌套或组合编写我们需要的配置信息。

字面常量

# 整数
2020

# 浮点数
0.618

# 字符串
# PS：在 YAML 中，字符串可以任意地使用单引号或双引号，甚至可以不使用引号
"Java"
'Gradle'
English

# 多行字符串
# 多行字符串可以使用 "|-" 作为引导，随后换行缩进1级（2个空格）书写文本内容
|-
  这是一个多行文本，当需要在文本中保留包括换行在内的特定格式时非常有用。
  
  编写人：Dragon1573
  日期：2020年9月3日

数组

# YAML 数组的每一个元素以一个 "-" 开头，其后空一格
- Section1
- Section2
- Section3
- Section4

对象（键值对）

# YAML 的对象是由键值对组成的，不论是键还是值都可以忽略引号直接书写
key: value

复合类型

YAML 复合类型是上面三种基础数据类型的嵌套与组合，我们将在后文中以实际的 YAML 配置文件为例进行讲解。

 

第1节　Course-info.yaml（课程配置）

示例代码

title: Tutorial
language: English
summary: |-
  Java course.
  Created: Sep 1, 2020, 9:35:00 PM.
programming_language: Java
programming_language_version: 8
environment: null
type: edu
solutions_hidden: true
vendor:
  name: Dragon1573
  email: vendor@example.com
  url: https://github.com/Dragon1573
content:
  - section1

配置说明 

名称	描述	值
title	课程标题	字符串
language	课程使用的文字语言	受支持的文字语言，例如英语 (English) 、汉语 (Chinese) 、日语 (Japanese)
summary	课程概述	单行或多行字符串
programming_language	课程使用的编程语言	受支持的编程语言，例如 Java, Kotlin, Scala, JavaScript, Rust
programming_language_version	【可选】编程语言的版本	数值或字符串
environment	【可选】课程需要的额外环境	例如 Kotlin 课程可以选择是否引入 Android 环境，Scala 课程可以选择使用 Gradle 或 SBT 进行管理
content	课程中包含的章节或课程目录名	由目录名称组成的列表
solutions_hidden	【可选】是否允许学习者提前查看并核对答案	布尔值（true / false），默认为 true
vendor	【可选】课程编写者的个人信息	开发者信息对象
vendor.name	课程编写者的名称	字符串
vendor.email	课程编写者的电子邮箱地址	电子邮箱
vendor.url	课程编写者的个人网站	URL
type	【可选】课程类型	枚举值：edu（离线教程项目）、coursera（在线教程配套项目）

 

第2节　section-info.yaml（章节配置）

示例代码

custom_name: MySection
content:
- lesson1

配置说明

名称	描述	值
custom_name	【可选】自定义章节名称（可以与目录名不同，IntelliJ IDEA Validator 没有加入这一项）	字符串
content	章节所拥有的课时子目录名称	由目录名称组成的数组

 

第3节　lesson-info.yaml（课时配置）

示例代码

type: lesson
custom_name: MyLesson
content:
- task1

配置说明

名称	描述	值
type	【可选】课程类型	枚举值：lesson / framework
custom_name	【可选】自定义课时名称（可以与目录名不同，IntelliJ IDEA Validator 没有加入这一项）	字符串
content	课时所拥有的任务子目录名称	由目录名称组成的数组

 

第4节　task-info.yaml（任务配置）

示例代码

type: output
custom_name: MyTask
files:
- name: src/Task.java
  visible: true
  placeholders:
  - offset: 73
    length: 18
    placeholder_text: /* Print out the string and go to a new line */
- name: test/output.txt
  visible: false

配置说明

名称	描述	值
type	任务类型	枚举值 描述 edu 基于单元测试的编程任务 theory 理论教学任务 output 基于输出文本匹配测试的编程任务 ide 集成开发环境教学任务 choice 单选或多选题任务
custom_name	【可选】自定义任务名称	字符串
files	被包含至任务中的文件	由文件对象（以下用 f 表示）组成的列表
f.name	文件相对任务根目录的路径	字符串
f.visible	文件是否对学习者可见	布尔值（true / false）
f.placeholders	【可选】文件中的答案占位符	由占位符对象（以下用 p 表示）组成的列表
f.p.offset	占位符相对文件开头的偏移量	数值
f.p.length	占位符长度	数值
f.p.placeholder_text	占位符实际向学习者显示的占位内容	字符串
f.p.dependency	【可选】当前占位符所依赖的其他占位符信息	依赖占位符对象（以下用 d 表示）
f.p.d.section	【可选】依赖占位符所在的章节目录名	字符串
f.p.d.lesson	依赖占位符所在的课时目录名	字符串
f.p.d.task	依赖占位符所在的任务目录名	字符串
f.p.d.file	依赖占位符所在文件相对所在任务根目录的路径	字符串
f.p.d.placeholder	依赖占位符在文件中的索引（从0开始）	数值
f.p.d.is_visible	是否在依赖占位符处显示当前占位符	布尔值（true / false），默认值为 true

---

下集预告

在这一课中，我们介绍了与 EduTools 有关的4种 YAML 文件的格式，现在我们应该能够非常自然地阅读这些配置文件了。在日常的开发过程中，很难遇到需要我们人为编辑这些 YAML 文件的情况，EduTools 中的 Course Creator 工具会辅助我们进行数字教材的编写工作。

下一节课，我们将着重讲解 Gradle 项目的2个核心配置文件：build.gradle 和 settings.gradle 。

一起去看看吧！