目录
[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个层次:
课程整体(Course),使用 course-info.yaml 进行配置各章节(Section),使用 section-info.yaml 进行配置课时(Lesson),使用 lesson-info.yaml 进行配置任务(Task),使用 task-info.yaml 进行配置
在这一课中,我们将介绍这4种 YAML 文件的格式并教大家如何读懂它。
第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, Rustprogramming_language_version【可选】编程语言的版本数值或字符串environment【可选】课程需要的额外环境例如 Kotlin 课程可以选择是否引入 Android 环境,Scala 课程可以选择使用 Gradle 或 SBT 进行管理content课程中包含的章节或课程目录名由目录名称组成的列表solutions_hidden【可选】是否允许学习者提前查看并核对答案布尔值(true / false),默认为 truevendor【可选】课程编写者的个人信息开发者信息对象vendor.name课程编写者的名称字符串vendor.email课程编写者的电子邮箱地址电子邮箱vendor.url课程编写者的个人网站URLtype【可选】课程类型枚举值: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 / frameworkcustom_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 。
一起去看看吧!