rmdex 0.2

快速入门

这个库主要可以做到以下几点

• 从一个模板笔记本生成一个练习笔记本和一个解决方案笔记本，前提是在模板笔记本的注释中给出一些标记，并

• 检查注释中指定的标记总数，以确保它们正确相加。

实用工具期望在 代码单元 中的注释有一些额外的标记来告诉它要做什么。

它同样乐意处理 R笔记本，格式为 RMarkdown，或以RMarkdown保存的 Jupyter 笔记本，可能使用 Jupytext。您可以在 https://github.com/matthew-brett/cfd2019/tree/master/_ok_exercises 上看到Jupyter笔记本的用法示例。

注释符号如下

• 一个练习单元（Jupyter）或块（R笔记本）是任何以注释开始的单元/块 #-（一个练习注释）或以 #<- 开始的。Rmdex只会修改输出练习和解决方案中的练习单元/块。

• 一个 练习注释 是任何以 #- 开头的注释。这些注释将未修改地传递到练习和解决方案笔记本中。

• 一个 插入注释 是以 #<- 开头，后跟一个空格的注释。随后的文本应作为一行，不应包含在解决方案中，而应包含在练习中。这允许模板向用户建议代码，这些代码将不会出现在解决方案中。此标记后的代码不需要是有效的语法。

• 一个 两节标记 是由 #<- 立即后跟一个换行符的行。这表示所有后续行，直到下一个 #<- 行（两节标记），应包含在练习和解决方案中。

• 一个 两行标记 是由 #<-- 立即后跟一个换行符的行。下一行应包含在解决方案和练习中。

• 如果任何行以 #<- 开头，后跟的不是空格、换行符或破折号，则这是错误。

• 任何其他代码行，包括以 # 开头的普通注释，都会从练习中删除。它们会出现在解决方案中。

• 一个 标记注释 是形式为 #- 5 分 / 100（目前为止总分为 10 分） 的 练习注释，其中 5 是此单元格的分数，100 是整个练习的总分，10 是到当前位置为止的总分（包括此单元格）。您可以使用 --check-marks 选项到主要的 rmdex 工具来检查这些数字的一致性（见下文）。

例如，模板可能有一个这样的单元格

```{r}
#- Here you will do a simple assignment.
#- More description of the assignment.
#- 5 marks / 100 (total 10 marks so far).
# This comment gets stripped from the exercise version of the cell.
# Also this one.  The next line adds the text after #<- to the exercise.
#<- my_variable = ...
# This comment and the next code line do not appear in the exercise.
my_variable = 10
#<-
# This comment does appear in the exercise, as well as the following code.
another_variable = 11
print("Something")
#<-
#<--
# This line follows the both-line marker, and appears in the exercise.
# This line does not.
# Starting at the previous line, we resume normal service.  This and
# the next line of comments do not appear in the exercise.
#
# The following marker causes everything to the end of the cell/chunk
# to appear in both exercise and solution:
#<->
print('This line appears in the exercise and solution')
print('as does this line')
```

上面的模板单元格在练习版本中产生以下内容

```{r}
#- Here you will do a simple assignment.
#- More description of the assignment.
#- 5 marks / 100 (total 10 marks so far).
my_variable = ...
# This comment does appear in the exercise, as well as the following code.
another_variable = 11
print("Something")
# This line follows the both-line marker, and appears in the exercise.
print('This line appears in the exercise and solution')
print('as does this line')
```

解决方案将包含

```{r}
#- Here you will do a simple assignment.
#- More description of the assignment.
#- 5 marks / 100 (total 10 marks so far).
# This comment gets stripped from the exercise version of the cell.
# Also this one.  The next line adds the text after #<- to the exercise.
# This comment and the next code line do not appear in the exercise.
my_variable = 10
# This comment does appear in the exercise, as well as the following code.
another_variable = 11
print("Something")
# This line follows the both-line marker, and appears in the exercise.
# This line does not.
# Starting at the previous line, we resume normal service.  This and
# the next line of comments do not appear in the exercise.
#
# The following marker causes everything to the end of the cell/chunk
# to appear in both exercise and solution:
print('This line appears in the exercise and solution')
print('as does this line')
```

rmdex 脚本读取模板，检查分数总和（使用选项 --check-marks），并生成练习。它还可以生成解决方案。以下是一些用法示例

# Generate the exercise from the template.
rmdex template_notebook.Rmd exercise_notebook.Rmd

# Generate the exercise and solution from the template.
rmdex template_notebook.Rmd exercise_notebook.Rmd solution_notebook.Rmd

# Check the marks total in the exercise, but do not write the exercise.
rmdex --check-marks template_notebook.Rmd

# Check the marks total in the exercise, and write the exercise.
rmdex --check-marks template_notebook.Rmd exercise_notebook.Rmd

# Write the solution only.
rmdex template_notebook.Rmd _ solution_notebook.Rmd

安装

pip install rmdex

代码

请参阅 https://github.com/matthew-brett/rmdex

在源分布中发布受 BSD 两条款约许可 - 请参阅文件 LICENSE。

travis-ci 慷慨地自动在 Python 3.6 至 3.8 版本下测试代码。

最新发布的版本在 https://pypi.python.org/pypi/rmdex

测试

• 安装 rmdex

• 安装 pytest 测试框架

  pip install pytest

• 使用以下命令运行测试

  pytest rmdex

支持

请在 rmdex 问题跟踪器 上提出问题。