Use comment syntax instead of jinja templates to denote solution code

[jhamrick]

In the master version, instructors may want to mark some code inline as solution-only, like this:

def some_function():
    ### BEGIN SOLUTION
    print("this is the solution!")
    ### END SOLUTION

Previously I did this with jinja, but @ellisonbg and I agreed that using comments is better because then the cells are pure python and can still be run without using nbgrader, and it's a clearer syntax for people who are unfamiliar with jinja.

[Carreau]

But does not the syntax of comment depend on the language ?

Also the "jinja" syntax is not specific to jinja it is used in many templating library of many languages :
http://liquidmarkup.org/ (ruby), http://mozilla.github.io/nunjucks/ (node)

I would say that people that use this are advance user, and that with comment-like templating you risk of reinventing your own thing. Also it is trivial to test wether an notebook with jinja-block is valid, or still contain jinja-block. When it's comment, you can mistype, and create an assigment notebook with solutions, so you have to check all by hand.

So please wait cost of comment more.

[ellisonbg]

The comment approach simplifies things dramatically:

• It allows instructors to write notebook that are valid code in whatever
  language/kernel they want. The jinja stuff essentially made an entirely new
  language that has to be installed by anyone who wants to run those
  notebooks. That is a horrible user experience and echoes the failed model
  of sweave, etc where the document the author writes is pretty much useless
  without additional processing.
• It allows the "master" notebook that is written by the instructor to be
  handed out to students as the official solutions without any further
  processing. This alone cuts out a ton of complex code from nbgrader.
• Requiring instructors to know jinja dramatically increases the cognitive
  load on instructors.
• The second you allow jinja in this type of context, you end up with
  massive risk of further scope creep - this was already happening with the
  TOC stuff - basically notebooks were starting to become big jinja templates
• that is the wrong direction.
• The workflow becomes much more complex.
• The code to implement the commend handling, while language dependent is
  super, super simple.

On Tue, Sep 16, 2014 at 1:02 AM, Matthias Bussonnier <
notifications@github.com> wrote:

But does not the syntax of comment depend on the language ?

Also the "jinja" syntax is not specific to jinja it is used in many
templating library of many languages :
http://liquidmarkup.org/ (ruby), http://mozilla.github.io/nunjucks/
(node)

I would say that people that use this are advance user, and that with
comment-like templating you risk of reinventing your own thing. Also it is
trivial to test wether an notebook with jinja-block is valid, or still
contain jinja-block. When it's comment, you can mistype, and create an
assigment notebook with solutions, so you have to check all by hand.

So please wait cost of comment more.

—
Reply to this email directly or view it on GitHub
#4 (comment).

Brian E. Granger
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

[jhamrick]

I was originally in favor of the jinja templates too -- hence why I had them :) -- but after discussing it and thinking about it more I'm fairly convinced that they are overkill, largely for the reasons @ellisonbg stated. Also, although there is less of a risk (because syntax errors will be caught), you do still run the risk of having mistyped jinja templates, like this:

{% if soluton %}
some stuff here
{% endif %}

Which would just render an empty string, because soluton isn't defined.