Weave.jl is like R markdown. So the document is markdown, and code is fenced, like:
# Here's a Header Some text with **bold** ```julia f(x) = x^2 + 4x + 2 f(4) ```
With Literate, the file is a julia file, and the explanations are in comments.
# # Here's a header # # Some text with **bold** f(x) = x^2 + 4x + 2 f(4)
I really like that in Literate, you can specify certain lines to only show up in Notebook exports,
or only show up in Markdown exports, and I like the fact that the file is a runable julia script (though with weave, you can export as a script). It’s also designed by one of the main contributors to Documenter, and so has a lot of nice features allowing the markdown export of Literate to play really nice with Documenter.
The major downside of Literate IMO is that there isn’t a great deal of tooling for things like Atom or VS code. So the markdown isn’t syntax highlighted, and when you write markdown with a lot of linebreaks as I do, it’s annoying to have to add the comment marker on every line (or the
#nb # if you want a notebook-filtered line) etc.
One of the benefits of Weave in its own right is that there are a lot of options for code blocks, like hiding the output of a cell (or hiding the code and only showing the output).
I tend to use Literate when my thing is code-heavy, when I want to run it as a script, or I want to use it with Documenter. I use Weave when there’s a lot of explanatory stuff or when I need more control over my code fences.
For what it sounds like you want to do, I’d probably recommend Weave, but only like 65/35. Hope this helps!