Cogbooks

Cogbooks

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

Installation Instructions

pip install cogbooks

Usage

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.

Forms of Delimiters

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

A Brief Primer on the Jupytext-Markdown Syntax

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
```

Creating a ipynb File with the Solutions Included

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

CogWorksBWSI / Cogbooks