Provides a tool for CogWorks instructors and TAs to filter instructor-only material out of Jupytext markdown files to create student Jupyter notebooks.
The idea of using jupytext for CogWorks is this: Editing notebooks is painful. Doing version control on notebooks is painful. Giving students notebooks is great. So, as instructors, we will develop all of our material in markdown files and then we will use cogbooks
to convert our markdown files to jupyter notebooks.
What is great about this is, cogbooks
introduces special markdown delimiters that permit instructors to include solutions and instructors-eyes-only comments in a markdown file, so that the file contains the full solutions. cogbooks
will then excise these sections when it converts the instructor-markdown files to student-notebooks.
For example, a markdown-file containing:
Make a list of the first 100 perfect squares
```python
# <COGINST>
solution = [i**2 for i in range(100)]
# </COGINST>
```
Running cogbooks
will then yield a jupyter notebook containing:
Make a list of the first 100 perfect squares
# STUDENT CODE HERE
pip install cogbooks
After installing Cogbooks, to convert a markdown file to a student notebook, run
cogbooks activitiy.md
Cogbooks will create the file activity_STUDENT.ipynb
in the same directory as activity.md
. Or, a directory to write student notebooks to can be specified with --dir
or -d
:
cogbooks activitiy.md --dir out_directory
Directories or multiple markdown files can be passed to Cogbooks:
cogbooks day1_directory/ activity1.md activity2.md
By default, existing notebooks will not be overwritten. Specifying --force
or -f
will have Cogbooks rewrite existing student notebooks.
Any instructor-only markdown file should be properly delimited. To delimit blocks of Python code, use <COGINST>
:
```python
# set-up code here
# <COGINST>
instructor-only code here
more instructor-only code
# </COGINST>
```
Running Cogbooks will then yield:
# set-up code here
# STUDENT CODE HERE
Alternatively, to remove single lines of code, use <COGLINE>
:
```python
# set-up code here
instructor-only code here # <COGLINE>
```
Applying Cogbooks will again result in:
# set-up code here
# STUDENT CODE HERE
To leave a "stubbed" assignment expression, one can use <COGSTUB>
to the right of an assignment (i.e. an expression using =
):
```python
x = 33.1 # <COGSTUB> compute `x`
```
Applying Cogbooks will leave behind a "stub" for that assignment:
x = # compute `x`
In markdown, use:
question here
<COGINST>
instructor-only answer here
</COGINST>
yielding,
question here
*SOLUTION HERE*
Lastly, to leave an instructor-only note in a markdown cell, use:
random text here
<COGNOTE>
instructor-only note here
</COGNOTE>
more random text here
which results in,
random text here
more random text here
See the official docs for a full rundown on Jupytext's syntax for encoding notebooks as markdown files.
The quick version of it is:
Markdown cells are delimited by:
<!-- #region -->
Anything in here, including code-blocks will be converted
into a markdown cell withing the notebook
<!-- #endregion -->
Python cells are delimited by:
```python
# this content will be converted into a python code-cell
# within the notebook
```
To convert a jupytext-markdown file to a standard Jupyter notebook, retaining the solutions, simply use jupytext
to do the conversion:
jupytext --to notebook my_markdown_file.md