Avoid highlighting output (#291)

.github/workflows/Docs.yml

@@ -22,6 +22,8 @@ jobs:
         with:
           version: '1'
 
+      - uses: julia-actions/cache@v1
+
       - run: julia --project=docs/ -e '
           using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
 

Project.toml

@@ -16,6 +16,7 @@ Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 Memoize = "c03570c3-d221-55d1-a50c-7939bbd78826"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 RelocatableFolders = "05181044-ff0b-4ac5-8273-598c1e38db00"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 SnoopPrecompile = "66db9d55-30c0-4569-8b51-7e840670fc0c"
 TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 URIs = "5c2747f8-b7ea-4ff2-ba2e-563bfd36b1d4"
@@ -28,10 +29,11 @@ tectonic_jll = "d7dd28d6-a5e6-559c-9131-7eb760cdacc5"
 CodeTracking = "1.0"
 DataFrames = "0.22, 1"
 Latexify = "0.15"
-LiveServer = "0.6, 0.7, 0.8, 0.9"
+LiveServer = "0.6, 0.7"
 Memoize = "0.4"
 ProgressMeter = "1"
 RelocatableFolders = "0.3"
+Revise = "3"
 SnoopPrecompile = "1"
 TOML = "1.0"
 URIs = "1.3"

defaults/julia_listings.tex

@@ -15,11 +15,10 @@
 \definecolor{highlight-darkblue}{HTML}{032f62}
 \definecolor{highlight-orange}{HTML}{e36209}
 
-\lstdefinelanguage{Output}{
+\lstdefinelanguage{output}{
   backgroundcolor = \color{highlight-lightbackground},
   % linespread is necessary to avoid white space https://tex.stackexchange.com/a/129380/92217.
   basicstyle = \JuliaMonoRegular\linespread{1.5}\scriptsize\color{highlight-gray},
-  numberstyle = \JuliaMonoRegular\scriptsize\color{highlight-red}, % not doing anything?
   commentstyle = \color[HTML]{AAAAAA},
   rulecolor = \color[HTML]{000000},
   postbreak = \usebox\mypostbreak,
@@ -44,7 +43,7 @@
   numbers = none, % Line numbers.
 }
 
-\lstdefinelanguage{Julia}{
+\lstdefinelanguage{julia}{
     % functions
     keywords=[3]{abs,abs2,abspath,accept,accumulate,accumulate!,acos,acos_fast,acosd,acosh,acosh_fast,acot,acotd,acoth,acsc,acscd,acsch,adjoint,adjoint!,all,all!,allunique,angle,angle_fast,any,any!,append!,apropos,ascii,asec,asecd,asech,asin,asin_fast,asind,asinh,asinh_fast,assert,asyncmap,asyncmap!,atan,atan2,atan2_fast,atan_fast,atand,atanh,atanh_fast,atexit,atreplinit,axes,backtrace,base,basename,beta,big,bin,bind,binomial,bitbroadcast,bitrand,bits,bitstring,bkfact,bkfact!,blkdiag,broadcast,broadcast!,broadcast_getindex,broadcast_setindex!,bswap,bytes2hex,cat,catch_backtrace,catch_stacktrace,cbrt,cbrt_fast,cd,ceil,cfunction,cglobal,charwidth,checkbounds,checkindex,chmod,chol,cholfact,cholfact!,chomp,chop,chown,chr2ind,circcopy!,circshift,circshift!,cis,cis_fast,clamp,clamp!,cld,clipboard,close,cmp,coalesce,code_llvm,code_lowered,code_native,code_typed,code_warntype,codeunit,codeunits,collect,colon,complex,cond,condskeel,conj,conj!,connect,consume,contains,convert,copy,copy!,copysign,copyto!,cor,cos,cos_fast,cosc,cosd,cosh,cosh_fast,cospi,cot,cotd,coth,count,count_ones,count_zeros,countlines,countnz,cov,cp,cross,csc,cscd,csch,ctime,ctranspose,ctranspose!,cummax,cummin,cumprod,cumprod!,cumsum,cumsum!,current_module,current_task,dec,deepcopy,deg2rad,delete!,deleteat!,den,denominator,deserialize,det,detach,diag,diagind,diagm,diff,digits,digits!,dirname,disable_sigint,display,displayable,displaysize,div,divrem,done,dot,download,dropzeros,dropzeros!,dump,eachcol,eachindex,eachline,eachmatch,edit,eig,eigfact,eigfact!,eigmax,eigmin,eigvals,eigvals!,eigvecs,eltype,empty,empty!,endof,endswith,enumerate,eof,eps,equalto,error,esc,escape_string,evalfile,exit,exp,exp10,exp10_fast,exp2,exp2_fast,exp_fast,expanduser,expm,expm!,expm1,expm1_fast,exponent,extrema,eye,factorial,factorize,falses,fd,fdio,fetch,fieldcount,fieldname,fieldnames,fieldoffset,filemode,filesize,fill,fill!,filter,filter!,finalize,finalizer,find,findfirst,findin,findlast,findmax,findmax!,findmin,findmin!,findn,findnext,findnz,findprev,first,fld,fld1,fldmod,fldmod1,flipbits!,flipdim,flipsign,float,floor,flush,fma,foldl,foldr,foreach,frexp,full,fullname,functionloc,gamma,gc,gc_enable,gcd,gcdx,gensym,get,get!,get_zero_subnormals,getaddrinfo,getalladdrinfo,gethostname,getindex,getipaddr,getkey,getnameinfo,getpeername,getpid,getsockname,givens,gperm,gradient,hash,haskey,hcat,hessfact,hessfact!,hex,hex2bytes,hex2bytes!,hex2num,homedir,htol,hton,hvcat,hypot,hypot_fast,identity,ifelse,ignorestatus,im,imag,in,include_dependency,include_string,ind2chr,ind2sub,indexin,indices,indmax,indmin,info,insert!,instances,intersect,intersect!,inv,invmod,invperm,invpermute!,ipermute!,ipermutedims,is,is_apple,is_bsd,is_linux,is_unix,is_windows,isabspath,isapprox,isascii,isassigned,isbits,isblockdev,ischardev,isconcrete,isconst,isdiag,isdir,isdirpath,isempty,isequal,iseven,isfifo,isfile,isfinite,ishermitian,isimag,isimmutable,isinf,isinteger,isinteractive,isleaftype,isless,isletter,islink,islocked,ismarked,ismatch,ismissing,ismount,isnan,isodd,isone,isopen,ispath,isperm,isposdef,isposdef!,ispow2,isqrt,isreadable,isreadonly,isready,isreal,issetgid,issetuid,issocket,issorted,issparse,issticky,issubnormal,issubset,issubtype,issymmetric,istaskdone,istaskstarted,istextmime,istril,istriu,isvalid,iswritable,iszero,join,joinpath,keys,keytype,kill,kron,last,lbeta,lcm,ldexp,ldltfact,ldltfact!,leading_ones,leading_zeros,length,less,lexcmp,lexless,lfact,lgamma,lgamma_fast,linearindices,linreg,linspace,listen,listenany,lock,log,log10,log10_fast,log1p,log1p_fast,log2,log2_fast,log_fast,logabsdet,logdet,logging,logm,logspace,lpad,lq,lqfact,lqfact!,lstat,lstrip,ltoh,lu,lufact,lufact!,lyap,macroexpand,map,map!,mapfoldl,mapfoldr,mapreduce,mapreducedim,mapslices,mark,match,matchall,max,max_fast,maxabs,maximum,maximum!,maxintfloat,mean,mean!,median,median!,merge,merge!,method_exists,methods,methodswith,middle,midpoints,mimewritable,min,min_fast,minabs,minimum,minimum!,minmax,minmax_fast,missing,mkdir,mkpath,mktemp,mktempdir,mod,mod1,mod2pi,modf,module_name,module_parent,mtime,muladd,mv,names,nb_available,ncodeunits,ndigits,ndims,next,nextfloat,nextind,nextpow,nextpow2,nextprod,nnz,nonzeros,norm,normalize,normalize!,normpath,notify,ntoh,ntuple,nullspace,num,num2hex,numerator,nzrange,object_id,occursin,oct,oftype,one,ones,oneunit,open,operm,ordschur,ordschur!,pairs,parent,parentindexes,parentindices,parse,partialsort,partialsort!,partialsortperm,partialsortperm!,peakflops,permute,permute!,permutedims,permutedims!,pi,pinv,pipeline,pointer,pointer_from_objref,pop!,popdisplay,popfirst!,position,pow_fast,powermod,precision,precompile,prepend!,prevfloat,prevind,prevpow,prevpow2,print,print_shortest,print_with_color,println,process_exited,process_running,prod,prod!,produce,promote,promote_rule,promote_shape,promote_type,push!,pushdisplay,pushfirst!,put!,pwd,qr,qrfact,qrfact!,quantile,quantile!,quit,rad2deg,rand,rand!,randcycle,randcycle!,randexp,randexp!,randjump,randn,randn!,randperm,randperm!,randstring,randsubseq,randsubseq!,range,rank,rationalize,read,read!,readandwrite,readavailable,readbytes!,readchomp,readdir,readline,readlines,readlink,readstring,readuntil,real,realmax,realmin,realpath,recv,recvfrom,redirect_stderr,redirect_stdin,redirect_stdout,redisplay,reduce,reducedim,reenable_sigint,reim,reinterpret,reload,relpath,rem,rem2pi,repeat,replace,replace!,repmat,repr,reprmime,reset,reshape,resize!,rethrow,retry,reverse,reverse!,reverseind,rm,rol,rol!,ror,ror!,rot180,rotl90,rotr90,round,rounding,rowvals,rpad,rsearch,rsearchindex,rsplit,rstrip,run,scale!,schedule,schur,schurfact,schurfact!,search,searchindex,searchsorted,searchsortedfirst,searchsortedlast,sec,secd,sech,seek,seekend,seekstart,select,select!,selectperm,selectperm!,send,serialize,set_zero_subnormals,setdiff,setdiff!,setenv,setindex!,setprecision,setrounding,shift!,show,showall,showcompact,showerror,shuffle,shuffle!,sign,signbit,signed,signif,significand,similar,sin,sin_fast,sinc,sincos,sind,sinh,sinh_fast,sinpi,size,sizehint!,sizeof,skip,skipchars,skipmissing,sleep,slicedim,sort,sort!,sortcols,sortperm,sortperm!,sortrows,sparse,sparsevec,spawn,spdiagm,speye,splice!,split,splitdir,splitdrive,splitext,spones,sprand,sprandn,sprint,spzeros,sqrt,sqrt_fast,sqrtm,squeeze,srand,stacktrace,start,startswith,stat,std,stdm,step,stride,strides,string,stringmime,strip,strwidth,sub2ind,subtypes,success,sum,sum!,sumabs,sumabs2,summary,supertype,svd,svdfact,svdfact!,svdvals,svdvals!,sylvester,symdiff,symdiff!,symlink,systemerror,take!,takebuf_array,takebuf_string,tan,tan_fast,tand,tanh,tanh_fast,task_local_storage,tempdir,tempname,thisind,tic,time,time_ns,timedwait,to_indices,toc,toq,touch,trace,trailing_ones,trailing_zeros,transcode,transpose,transpose!,tril,tril!,triu,triu!,trues,trunc,truncate,trylock,tryparse,typeintersect,typejoin,typemax,typemin,unescape_string,union,union!,unique,unique!,unlock,unmark,unsafe_copy!,unsafe_copyto!,unsafe_load,unsafe_pointer_to_objref,unsafe_read,unsafe_store!,unsafe_string,unsafe_trunc,unsafe_wrap,unsafe_write,unshift!,unsigned,uperm,valtype,values,var,varinfo,varm,vcat,vec,vecdot,vecnorm,versioninfo,view,wait,walkdir,warn,which,whos,widemul,widen,withenv,workspace,write,xor,yield,yieldto,zero,zeros,zip,applicable,eval,fieldtype,getfield,invoke,isa,isdefined,nfields,nothing,setfield!,throw,tuple,typeassert,typeof,uninitialized,undef},%
     % module functions
@@ -61,19 +60,30 @@
     morestring=[s]{"}{"},
     morestring=[m]{'}{'},
     literate=*{-}{-}1,
-    alsoletter=!?
+    alsoletter=!?,
+    % Thanks to https://tex.stackexchange.com/questions/23634.
+    literate =%
+      {0}{{{\color{highlight-blue}0}}}1
+      {1}{{{\color{highlight-blue}1}}}1
+      {2}{{{\color{highlight-blue}2}}}1
+      {3}{{{\color{highlight-blue}3}}}1
+      {4}{{{\color{highlight-blue}4}}}1
+      {5}{{{\color{highlight-blue}5}}}1
+      {6}{{{\color{highlight-blue}6}}}1
+      {7}{{{\color{highlight-blue}7}}}1
+      {8}{{{\color{highlight-blue}8}}}1
+      {9}{{{\color{highlight-blue}9}}}1
+      {│}{|}1% Remove those tricky Unicode symbols used by PrettyTables.jl.
 }
 
 % Thanks to https://tex.stackexchange.com/questions/570945.
 \newsavebox\mypostbreak
 \savebox\mypostbreak{\raisebox{0ex}[0ex][0ex]{\ensuremath{\color{red}\hookrightarrow\space}}}
 
 \lstdefinestyle{julia_style}{
-  language = Julia,
   backgroundcolor = \color{highlight-background},
   % linespread is necessary to avoid white space https://tex.stackexchange.com/a/129380/92217.
   basicstyle = \JuliaMonoRegular\linespread{1.5}\scriptsize\color{highlight-gray},
-  numberstyle = \JuliaMonoRegular\scriptsize\color{highlight-red}, % not doing anything?
   keywordstyle = [1]{\JuliaMonoBold\color{highlight-red}},
   keywordstyle = [2]{\color{highlight-orange}},
   keywordstyle = [3]{\color{highlight-darkblue}},
@@ -98,18 +108,5 @@
   columns = fullflexible,
   keepspaces = true,
   numbers = none, % Line numbers.
-  % Thanks to https://tex.stackexchange.com/questions/23634.
-  literate =%
-    {0}{{{\color{highlight-blue}0}}}1
-    {1}{{{\color{highlight-blue}1}}}1
-    {2}{{{\color{highlight-blue}2}}}1
-    {3}{{{\color{highlight-blue}3}}}1
-    {4}{{{\color{highlight-blue}4}}}1
-    {5}{{{\color{highlight-blue}5}}}1
-    {6}{{{\color{highlight-blue}6}}}1
-    {7}{{{\color{highlight-blue}7}}}1
-    {8}{{{\color{highlight-blue}8}}}1
-    {9}{{{\color{highlight-blue}9}}}1
-    {│}{|}1% Remove those tricky Unicode symbols used by PrettyTables.jl.
 }
 \lstset{style=julia_style}

defaults/style.css

@@ -280,7 +280,7 @@ pre.output {
 }
 
 .output code {
-  background: hsl(0, 0%, 98%);
+  background: hsl(0, 0%, 98%) !important;
 }
 
 b, strong {

docs/Project.toml

@@ -10,7 +10,6 @@ DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 IOCapture = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
 Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
-MCMCChains = "c7f686f2-ff18-58e9-bc7b-31028e88f75d"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
@@ -19,5 +18,4 @@ TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 
 [compat]
 Latexify = "0.15"
-MCMCChains = "5"
 Reexport = "1.1"

docs/contents/demo.md

@@ -32,8 +32,8 @@ M.julia_version() = "This book is built with Julia $VERSION."
 Next, ensure that you call `using Books; gen(; M)`, where `M = YourModule`.
 Alternatively, if you work on a large project and want to only generate the output for one or more Markdown files in `contents/`, such as `index.md`, use
 
-```jl
-M.markdown_gen_example()
+```language-julia
+gen("index")
 ```
 
 Calling `gen` will place the text
@@ -76,22 +76,29 @@ julia> gen()
 
 To run this method automatically when you make a change in your package, ensure that you loaded [Revise.jl](https://github.com/timholy/Revise.jl) before loading your package and run
 
-```
+```language-julia
 entr(gen, ["contents"], [M])
 ```
 
 where M is the name of your module.
 Which will automatically run `gen()` whenever one of the files in `contents/` changes or any code in the module `M`.
-To only run `gen` for one file, such as "contents/my_text.md", use:
+To only run `gen` for one file, such as `contents/my_text.md`, use:
 
+```language-julia
+entr(["contents"], [M]) do
+    gen("my_text")
+end
 ```
-mygen() = gen("my_text")
-entr(mygen, ["contents"], [M])
+
+Or, the equivalent helper function exported by `Books.jl`:
+
+```language-julia
+entr_gen("my_text")
 ```
 
-With this, `mygen` will be called every time something changes in one of the files in the contents folder or when something changes in your module `M`.
+With this, `gen("my_text")` will be called every time something changes in one of the files in the contents folder or when something changes in your module `M`.
 Note that you have to run this while `serve` is running in another terminal in the background.
-Then, your Julia code is executed and the website is automatically updated every time you change something in "content" or your module `M`.
+Then, your Julia code is executed and the website is automatically updated every time you change something in `content` or your module `M`.
 
 In the background, `gen` passes the methods through `convert_output(expr::String, path, out::T)` where `T` can, for example, be a DataFrame or a plot.
 To show that a DataFrame is converted to a Markdown table, we define a method
@@ -119,8 +126,6 @@ Refer to @tbl:my_table with
 @tbl:my_table
 ```
 
-> @tbl:my_table
-
 To show multiple objects, pass a `Vector`:
 
 ```jl
@@ -394,8 +399,6 @@ This time, we also pass `link_attributes` to Pandoc (@fig:makie) to shrink the i
 
 ### Multilingual books
 
-For an example of a multilingual book setup, say English and Chinese, see the book by [Jun Tian](https://github.com/LearnJuliaTheFunWay/LearnJuliaTheFunWay.jl).
-
 For an example of a multilingual book setup, say English and Chinese, see <https://juliadatascience.io>.
 
 ### Footnotes
@@ -416,10 +419,10 @@ Some sentence[^foot].
 
 When your method returns an output type `T` which is unknown to Books.jl, it will be passed through `show(io::IO, ::MIME"text/plain", object::T)`.
 So, if the package that you're using has defined a new `show` method, this will be used.
-For example, for `MCMCChains`,
+For example, for a grouped DataFrame:
 
 ```jl
-@sco M.chain()
+sco("groupby(DataFrame(; A=[1]), :A)")
 ```
 
 ### Note box
@@ -519,7 +522,7 @@ Ligatures from JuliaMono are disabled. For example, none of these symbols are co
 ### Long lines in code blocks
 
 ```language-plain
-When code or output is getting too long, a horizontal scrollbar is visible on the website to scroll horizontally.
+When code or output is getting too long, a horizontal scrollbar is visible on the website to scroll horizontally and a red arrow is visible in the PDF.
 ```
 
 ### Code blocks in lists

docs/contents/getting-started.md

@@ -12,9 +12,9 @@ M.serve_example()
 To generate all the Julia output (see @sec:embedding-output for more information) use
 
 ```
-$ julia --project -e  'using Books; using MyPackage; M = MyPackage'
+$ julia --project -e  'using Books; using MyPackage'
 
-julia> gen()
+julia> gen(; M)
 [...]
 Updating html
 ```

docs/src/BooksDocs.jl

@@ -3,7 +3,6 @@ module BooksDocs
 import Books
 import IOCapture
 import Latexify
-import MCMCChains
 import Statistics
 import TOML
 

docs/src/includes.jl

@@ -27,25 +27,25 @@ function docs_metadata()
     path = joinpath(pkgdir(BooksDocs), "metadata.yml")
     text = read(path, String)
     text = replace(text, '`' => "\\`")
-    code_block(text)
+    output_block(text)
 end
 
 function default_metadata()
     path = joinpath(Books.DEFAULTS_DIR, "metadata.yml")
     text = read(path, String)
-    code_block(text)
+    output_block(text)
 end
 
 function docs_config()
     path = joinpath(pkgdir(BooksDocs), "config.toml")
     text = read(path, String)
-    code_block(text)
+    output_block(text)
 end
 
 function default_config()
     path = joinpath(Books.DEFAULTS_DIR, "config.toml")
     text = read(path, String)
-    code_block(text)
+    output_block(text)
 end
 
 my_table() = DataFrame(U = [1, 2], V = [:a, :b], W = [3, 4])
@@ -101,27 +101,8 @@ code_example_table() = code("""
     DataFrame(A = [1, 2], B = [3, 4], C = [5, 6])
     """)
 
-function markdown_gen_example()
-    c = IOCapture.capture() do
-        M = BooksDocs
-        # Update html set to false to avoid Pandoc errors.
-        gen("index"; log_progress=false, call_html=false)
-    end
-
-    """
-    ```
-    gen("index")
-    ```
-
-    ```output
-    $(rstrip(c.output))
-    Updating html
-    ```
-    """
-end
-
 julia_version_example() = """
-```
+```output
 This book is built with Julia $VERSION.
 ```"""
 
@@ -191,9 +172,5 @@ function makiejl()
     Options(p; caption, label, link_attributes)
 end
 
-fib(n) = n <= 1 ? n : fib(n - 1) + fib(n - 2)
-
-chain() = (fib(44); MCMCChains.Chains(rand(10, 1)))
-
 const BACKTICK = '`'
 export BACKTICK

src/Books.jl

@@ -21,6 +21,7 @@ using InteractiveUtils: gen_call_with_extracted_types
 using Markdown: MD
 using Memoize: @memoize
 using ProgressMeter: ProgressMeter
+using Revise: entr
 using SnoopPrecompile: SnoopPrecompile, @precompile_setup, @precompile_all_calls
 using pandoc_crossref_jll: pandoc_crossref_path
 using pandoc_jll: pandoc
@@ -48,7 +49,7 @@ export code, ImageOptions, Options
 
 export code_block, output_block
 export @sc, sc, CodeAndFunction, @sco, sco, scob
-export gen
+export gen, entr_gen
 export serve
 
 @precompile_setup begin

src/build.jl

@@ -268,7 +268,9 @@ end
     <script>
     document.addEventListener('DOMContentLoaded', (event) => {
         document.querySelectorAll('pre').forEach((el) => {
-            hljs.highlightElement(el);
+            if (!el.classList.contains('output')) {
+                hljs.highlightElement(el);
+            }
         });
     });
     </script>
@@ -342,10 +344,13 @@ function pdf(; project="default")
             "--variable=build-info:$(today())";
             extra_args
         ]
+
         output_tex_filename = joinpath(BUILD_DIR, "$file.tex")
-        println("Wrote $output_tex_filename (for debugging purposes)")
         tex_output = "--output=$output_tex_filename"
-        out = call_pandoc([args; tex_output])
+        call_pandoc([args; tex_output])
+        @info "Wrote $output_tex_filename (for debugging purposes)"
+
+        out = call_pandoc([args; output])
 
         if !isnothing(out)
             println("Built $output_filename")

src/generate.jl

@@ -379,7 +379,8 @@ function gen(
             @error "Expected length of `paths` to be 1 when using `block_number`."
         end
         path = only(paths)
-        filter!(e -> e.path == path && e.block_number == block_number, exprs)
+        _filename(path) = splitext(_callpath(path))[1]
+        filter!(e -> _filename(e.path) == path && e.block_number == block_number, exprs)
     end
 
     n = length(exprs)
@@ -440,6 +441,18 @@ Convenience method for passing `path::AbstractString` instead of `paths::Vector`
 """
 function gen(path::AbstractString, block_number::Union{Nothing,Int}=nothing; kwargs...)
     path = string(path)::String
-    gen([path]; kwargs...)
+    return gen([path], block_number; kwargs...)
 end
 precompile(gen, (String,))
+
+"""
+    entr_gen(path::AbstractString, [block_number]; kwargs...)
+
+Execute `gen(path, [block_number]; M, kwargs...)` whenever files in `contents` or code in module `M` changes.
+This is a convenience function around `Revise.entr(() -> gen(...), ["contents"], [M])`.
+"""
+function entr_gen(path::AbstractString, block_number=nothing; M, kwargs...)
+    entr(["contents"], [M]) do
+        gen(path, block_number; M, kwargs...)
+    end
+end