Empty code cells in Jupyter notebook and errors allowed?

[dlfivefifty]

I've run into a few issues trying to use this:

1. It doesn't seem to let me do comments inside functions without code. E.g. I have a problem sheet which has the following template:

function ==(x::Rat, y::Integer)
    # TODO: implement
end

But it is treating the # TODO as a new cell. If I change to the following it works however:

function ==(x::Rat, y::Integer)
    1 # TODO: implement
end

2. How do I make an empty code block? I.e. in the Jupyter notebook I want an empty cell after each Problem for students to write code.
3. Any way to say errors are allowed? Sometimes I want to show a bit of code that errors.

[dlfivefifty]

For (1) I found the comment in the docs that a ## is treated as a Julia comment.

This gives a workaround for (2): User ## to indicated an empty cell. It does put a # in the cell so not a complete solution.

[JeffFessler]

For (1) I found the comment in the docs that a ## is treated as a Julia comment.

I came here to report the same issue about comments inside functions and now I have also adopted the ## approach. It is slightly ungainly but acceptable. Personally I wish that any indented # within a function block (or if or let etc.) was treated as a Julia comment, so that the source Julia code would look more usual, but I can live with ##. At least it looks right in the output markdown.

[fredrikekre]

Hi, sorry for the late reply.

Just to provide some context; from the very beginning the Markdown indicator was #' because that is what Weave.jl used (at leat back then). However, in the release announcement this was something people didn't really like, and using plain # was suggested instead, at the cost of having to use ## for actual comments (see first 10 or so replies here: https://discourse.julialang.org/t/ann-literate-jl/10651/ and some discussion in #3). This was then changed in #4, and I think it was the right choice. Looking at Literate.jl documents in the wild, it is far more common with Markdown lines compared to comment lines.

Personally I wish that any indented # within a function block [...]

Allowing whitespace before the indicator was added in #6 but perhaps that was a mistake. The reason for it is that Literate.jl and Documenter.jl support partial blocks, which allows for interweaving markdown with code, even in the middle of a function. Allowing whispace in front thus enables you to write

function foo()
    this + is + code
    # this is markdown
    this + is + also - code
end

instead of

function foo()
    this + is + code
# this is markdown
    this + is + also - code
end

You can see this in action here: https://ferrite-fem.github.io/Ferrite.jl/stable/examples/ns_vs_diffeq/ where the function assemble_stokes_matrix has some markdown in the middle of the function. However, this feature didn't turn out that nice IMO since it looks a bit strange. (I got the inspiration from deal.ii documentation https://www.dealii.org/current/doxygen/deal.II/step_3.html, but it somehow doesn't feel as split up there.)

In any case, using a custom preprocessor such as (untested)

function preprocess(str)
    # Replace multiples of four space followed by # with ##
    return replace(str, r"^((?: {4})+#)"m => s"\1#")
end

Would allow you to write your documents like that.

[fredrikekre]

And regarding empty cells, those are filtered out. For the specific usecase mentioned above though, perhaps it would be more instructive that the empty, to be filled in, cells contain a comment such as

# Please write your code here

which is pretty easy to achieve.

[fredrikekre]

Also forgot about deliberate errors: For Documenter output you can use try-catch that you # hide, but for notebooks that doesn't really work. I don't really have a good suggestion. Usually if you have errors you want Julia to throw so I think the current default is the most useful at least.

[JeffFessler]

Thanks for the preprocess hint - I might give that a try!
I admit that the "inconvenience" of typing ## is a first-world problem...
Overall I love Literate and its design and syntax. Thank you!

[dlfivefifty]

Personally I'd vote to revert #6 but I can live with the current behaviour.

FYI I'm now using Literate.jl for my labs: https://github.com/Imperial-MATH50003/MATH50003NumericalAnalysis/blob/main/src/labs/lab2.jl

[JeffFessler]

Personally I'd vote to revert #6 but I can live with the current behaviour.

Same here (both voting and living with 😄 ). The benefit is that you can include math in the markdown, but a drawback is that the code block gets chopped up so users can't use the copy icon to grab the entire function.