Literate programming workflow with ordinary jl scripts

I am trying to do some literate programming.

The workflow I want to pursue is writing valid Julia code in a script that I can execute with VSCode to see the results, add markdown content in comments, and then produce some output file, ideally in markdown I can later post-process.

EDIT 1: I ended up answering my own initial question… I was struggling with multiline comments, and was using docstrings (“”" “”") instead… multilinecomments (#= =#) for the win. It seems that docstrings are part of the code, and that literate programming is done with comments only.

EDIT 2: However, I’m still facing some issues. I don’t know how to capture output with Literate.jl, and I’m still struggling with multiline comments in Weave.jl, so I don’t know which is the best tool. Maybe use Literate + Weave, or Literate + Documenter?

Anyway, if anyone is doing literate programming and wants to share tips or their favourite workflow, I would be glad to hear.

1 Like

Pluto notebooks are just Julia scripts with markdown strings interleaving code blocks. Would that not work?

I think the input of Pluto notebooks are small code blocks, and the output is a regular .jl script. I’m looking for something where the input is a .jl script and the output is a document.

Ok, it turns out that Literate.jl can capture output as well…

Literate.markdown("test.jl", execute=true, documenter=false, credit=false)

This command generates some very general-purpose markdown, and is really close to what I was looking for.

1 Like

You might want to try to use Quarto It will have a separate vscode extension.

I’ll check out their vscode integration, but it looks like the workflow starts with markdown + placing code within code fences. So, at first this will collide with the VS code REPL integration…

I think I almost got it with Literate (+ probaby CommonMark.jl)… but maybe I’m insisting on the wrong approach of starting with a regular julia script, and literate programming just tends to gravitate a lot towards notebooks these days.