Open dlfivefifty opened 1 year ago
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.
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.
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.
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.
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.
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!
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
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.
I've run into a few issues trying to use this:
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:But it is treating the # TODO as a new cell. If I change to the following it works however: