Merge pull request #852 from timholy/teh/docs_REPL

Add docs on trick for handling REPL

docs/make.jl

@@ -10,6 +10,7 @@ makedocs(;
         "config.md",
         "cookbook.md",
         "limitations.md",
+        "tricks.md",
         "debugging.md",
         "internals.md",
         "user_reference.md",

docs/src/index.md

@@ -130,7 +130,7 @@ Revise is fairly ambitious: if all is working, subject to a few [Limitations](@r
 - any package that you load with `import` or `using`
 - any script you load with [`includet`](@ref) (see [Configuring the revise mode](@ref) for important default restrictions on `includet`)
 - any file defining `Base` julia itself (with `Revise.track(Base)`)
-- any of Julia's standard libraries (with, e.g., `using Unicode; Revise.track(Unicode)`)
+- any of Julia's standard libraries (with, e.g., `using Unicode; Revise.track(Unicode)`). Some stdlibs may require special handling; see, for example, a trick for modifying [REPL](@ref editREPL).
 - any file defining `Core.Compiler` (with `Revise.track(Core.Compiler)`)
 
 The last one requires that you clone Julia and build it yourself from source.
@@ -146,10 +146,11 @@ With Revise, you can
 
 - fix the bug while simultaneously developing a high-quality test
 - verify that your test passes with the fixed code
+- commit the test, but not the fix
 - `git stash` your fix and check that your new test fails on the old code,
   thus verifying that your test captures the essence of the former bug (if it doesn't fail,
   you need a better test!)
-- `git stash pop`, test again, commit, and submit
+- `git stash pop`, test again, commit the fix, and submit
 
 all without restarting your Julia session.
 

docs/src/tricks.md

@@ -0,0 +1,23 @@
+# Tricks
+
+## [Editing code that defines REPL](@id editREPL)
+
+Updating the code in Julia's REPL stdlib requires some extra trickery, because modified method definitions can't be deployed until you exit any currently-running REPL functions, like those handling the prompt that you're using to interact with Julia. A workaround is to create a sub-REPL that you can shut down, and then restart a new one whenever you want to test new code:
+
+```
+using Revise
+using REPL
+Revise.track(REPL)
+
+term = REPL.Terminals.TTYTerminal("dumb", stdin, stdout, stderr)
+repl = REPL.LineEditREPL(term, true)
+Revise.retry()
+
+while true
+    @info("Launching sub-REPL, use `^D` to reload, `exit()` to quit.")
+    REPL.run_repl(repl)
+    Revise.retry()
+end
+```
+
+Many thanks to `staticfloat` for [contributing](https://github.com/timholy/Revise.jl/issues/741) this suggestion.