From 08df88d5ed02686397b06241ec0c04e969ff4f0c Mon Sep 17 00:00:00 2001
From: Morten Piibeleht <morten.piibeleht@gmail.com>
Date: Tue, 23 Mar 2021 04:16:45 +1300
Subject: [PATCH] Print out executed code blocks when in debug mode (#137)

---
 docs/src/tips.md | 32 ++++++++++++++++++++++++++++++++
 src/Literate.jl  |  5 +++++
 2 files changed, 37 insertions(+)

diff --git a/docs/src/tips.md b/docs/src/tips.md
index 7a75af5..83201d7 100644
--- a/docs/src/tips.md
+++ b/docs/src/tips.md
@@ -39,3 +39,35 @@ HTML formats.
     img = plot(...)
     img = DisplayAs.Text(DisplayAs.PNG(img))
     ```
+
+### [Debugging code execution](@id debug-execution)
+
+When Literate is executing code (i.e. when `execute = true` is set), it does so quietly.
+All the output gets captured and nothing gets printed into the terminal.
+This can make it tricky to know where things go wrong, e.g. when the execution stalls due
+to an infinite loop.
+
+To help debug this, Literate has an `@debug` statement that prints out each code block that
+is being executed. In general, to enable the printing of Literate's `@debug` statements, you
+can set the `JULIA_DEBUG` environment variable to `"Literate"`.
+
+The easiest way to do that is to set the variable in the Julia session before running
+Literate by doing
+
+```julia
+ENV["JULIA_DEBUG"]="Literate"
+```
+
+Alternatively, you can also set the environment variable before starting the Julia session, e.g.
+
+```sh
+$ JULIA_DEBUG=Literate julia
+```
+
+or by wrapping the Literate calls in an `withenv` block
+
+```julia
+withenv("JULIA_DEBUG" => "Literate") do
+    Literate.notebook("myscript.jl"; execute=true)
+end
+```
diff --git a/src/Literate.jl b/src/Literate.jl
index 1ffdc79..bb6ef16 100644
--- a/src/Literate.jl
+++ b/src/Literate.jl
@@ -703,6 +703,11 @@ end
 
 # Execute a code-block in a module and capture stdout/stderr and the result
 function execute_block(sb::Module, block::String)
+    @debug """execute_block($sb, block)
+    ```
+    $(block)
+    ```
+    """
     # Push a capturing display on the displaystack
     disp = LiterateDisplay()
     pushdisplay(disp)