Using PlutoTest.@test (s) As Examples In DocStrings

[unnamedunknownusername]

Hi there

This is more of a feature request than an issue so feel free to move to correct thread.

I have this idea that tests could be used as "examples" in documentation/docstring and pluto provides the perfect place to to have reactive testing. The end goal would be to lessen the maintenance burden when changing various bits of functions/inputs/ making sure everything is in sync. basically I was wondering if

So currently I have to manually insert a function call in $ interpolated it and keep all calls up to date. Like this

"""
julia> myfunc0(1)
julia> $(myfunc0(1))
"""
function myfunc0(x)
     x+0
end

as a doc string

Instead it would be really nice if we could do something like this

"""
$(firstTestMyFunc1)

$(@MakeExampleFromTest(seccondTestMyFunc2))
"""
function myfunc1(x)
	x+1
end

i.e. use a macro or something that did all the manual work for you and basically regurgitated everything between a

test1 = let 
... #test and variable definitions here
end

block of a test. Again the idea is to basically make a docSting with examples that are REPL commands which a beginner or user looking at the documentation could use to get the same output. and to automate all of this so that maintenance is minimal

However currently this causes a cyclic reference and I am not sure if there is a solution to this.
I'm very willing to try create something and I have looked into Julia macros and expressions and unquoting julia code but am still a novice in this regards so some guidance from someone with more experience would be helpful/appreciated. And i am not the best at html/web-dev so some roadmap there would also be helpful

For more info you can look at this example notebook below (had o make it text)

• myfunc0 shows how I currently manually have to do it
• my func1() errors due to the cyclic reference (and shows how I would want to splice the test in the docString
• my func2() shows a bare minimum of how I would want the the test to display in the docString
• and myfunc3() shows ideally how I would want it displayed
  
  TestsAsExamples.txt