哈佛IACS课程的命令行工具
iacs-cli的Python项目详细描述
IACS客户端
什么是iacs cli?
iacs cli是一个课程网站生成器,由 鹈鹕,一个python静态站点 生成器,使课程教师能够快速转换课程 为学生和公众提供网络内容。一些挑战 IACS课程讲师面临的问题包括:
经常在jupyter笔记本、r标记文档或 幻灯片。不幸的是,课程教师需要上传 这些材料必须与课程分开保存在网站上 内容。这意味着教师必须精通html、css,有时 javascript以及网站部署。理想情况下,课程讲师应该 全力以赴开发课程内容并委派 为他人开发网站。
每一位IACS课程讲师都会组织自己的课程项目 项目组织结构。这使得导航课程材料 对于一个新的课程指导老师来说是一个挑战。
此外,由于课程内容缺乏约定 在网上展示,学生们也面临着快速找到材料的困难 关于他们好奇的话题。理想情况下,IACS课程网站应该遵循 始终如一的"观感",寻找学习内容 直观、简单。课程讲师应该能够快速利用现有内容 课程的前一个迭代,而不是启动课程项目 从零开始。此外,如果课程材料的组织方式相同 按照惯例,课程老师从 其他课程,并将其整合到另一个课程中。例如,如果cs109 数据科学必须借鉴AM207蒙特卡洛方法的概念,CS109 如果CS109课程老师有 得到了适当的认可,并对材料进行了小的修改和 不关心HTML和CSS。
iacs cli
通过强制课程组织来缓解这些问题
静态html和css文件的约定和自动生成。在
除了静态网站生成之外,还有iacs cli的其他功能
包括:
- 自动主题索引生成-课程内容可以围绕 主题如果课程设计者在内容的元数据中提供"标记"信息。
- 按主题搜索课程内容–如主题索引,如果课程设计者 提供"标签"信息,可按感兴趣的主题搜索网站。
- 可定制的网页设计,只需最少的HTML和CSS知识。
无需触摸HTML或CSS,课程设计师可以自定义 尽管网站保持了IACS课程一贯的"感觉"。
安装/设置
iacs cli
是一个pypi包。为了通过pypi安装,使用pip
命令控制台中的命令:
$pip安装iacs cli
此命令将安装IACS-Cli及其依赖项:
- 单击
- 鹈鹕
- 降价
- Gitpython
工作流程
- 创建一个新项目-将命令控制台转到要放置课程内容的目录,并使用以下命令创建课程:
$IACS创建"课程名称"
我们希望讲师使用的标准惯例是yyyy课程名称。
例如,对于2017年秋季的CS109A,我们将课程项目命名为2017-CS109A。
- 创建主页-转换为主页的标记文档 当您创建项目目录时,将预先填充网站的。它是 位于content/index.md中
您必须提供课程名称和文档创建日期。
不要修改"另存为:index.html",除非您不想将此文档用作课程网站的主页
- 创建其他页面,如教学大纲、政策、资源等。
不是课程内容的每一页,如教学大纲或资源页,
在内部创建标记文档(包含标题、slug和日期元数据)
目录content/pages/
这里,slug指的是从 文件。例如,slug:deculus将生成一个指向 教学大纲页面:http://<;课程网站>;/页面/教学大纲.html
- 创建计划页
iacs cli
使课程设计者能够使用
CSV文件。在发布过程中,命令行工具将自动
将csv表转换为降价表,然后将其转换为
到HTML表。
当课程设计器创建新项目时,schedule.csv文件将
在content/pages/
目录中自动创建。使用excel或类似工具
编辑schedule.csv文件的电子表格软件,如下所示:
请注意,任何与标记文档标题匹配的单元格内容, 然后创建的标记将自动将标记文档链接到 相应的文件。这个自动生成的降价表将 已转换为HTML表格,其中包含指向课程内容的可单击链接:
- 编辑课程内容
有两种方法可以创建和编辑课程内容。一个人可以创造 使用降价或ipython笔记本的页面。
建议的目录结构:
ProjectDirectory
content/
labs/
lectures/
pages/
sections/
index.md
docs/
plugins/
ipynb/
tipue_search/
themes/
static/
templates/
config.py
README.md
- 包括元数据 为了转换用降价或ipython笔记本写的课程内容, 必须在文档顶部提供以下元数据信息:
- 标题
- 类别
- 弹头
- 作者
- 日期
- 标记–可选,但强烈建议用于主题索引和搜索
在降价文档中,这可能类似于以下示例:
对于ipython笔记本的元数据,必须使用 名称相同,但前缀为"-meta"。例如(见下文)。 对于讲师1213_noteboo.ipynb,创建讲师1213_notebook.ipynb-meta 并在文档顶部提供元数据信息。
- 链接项目中的文档
要在课程中的文档之间创建内部链接,请使用标记语法创建前缀为{filename}的链接:
(<;说明>;)[{filename}<;文件路径>;]
请参见下面的示例:
- 包括静态文件,如*.jpg、*.pdf和*.png
用于指向静态文件(如pdf或嵌入jpeg或png图像)的链接 在标记文档中,使用{attach}前缀:
(<;description>;)[{attach}<;path_to_file>;]
- 创建网站内容后,课程设计者必须生成 在根目录中使用以下命令的html和css文档 项目的:
$IACS发布
此命令将用静态html和css文件填充doc/目录 对于网站。要预览网站,请在内部使用以下命令 根目录:
< Buff行情>$IACS启动
此命令将启动端口号为8000的python本地主机服务器。正常开放 打开浏览器并访问http://localhost:8000/" rel="nofollow">http://localhost:8000/
- 打开GitHub页面
提交git repo并上传到github.com。在"设置"页中,启用github 页面并选择主分支/docs文件夹作为其来源:
命令参考
- 创建新项目
$IACS创建"课程名称"
- 发布内容
$IACS发布
- 启动本地主机Web服务器
$IACS启动
- 复制现有课程项目
$IACS复制"现有课程目录""课程名称"