Merge pull request #223 from JuliaPlots/as/betterembedding

Better example embedding

.gitlab-ci.yml

@@ -28,7 +28,7 @@ gallerytest:
       - apt-get install -y cmake xorg-dev mesa-utils p7zip-full
 
   script:
-    - mkdir $JULIA_DEPOT_PATH # Pkg.jl#325
+    - mkdir -p $JULIA_DEPOT_PATH # Pkg.jl#325
     - glxinfo | grep 'version'
     - julia -e 'using InteractiveUtils; versioninfo()'
     - julia --project -e "using Pkg;

docs/.gitignore

@@ -1,4 +1,7 @@
+# Documenter autogenerated things
 build
+
+# Generated pages
 axis.md
 examples-database.md
 examples-for-tags.md
@@ -7,7 +10,11 @@ examples-*.md
 functions-overview.md
 plot-attributes.md
 signatures.md
+typetrees.md
+src/typetrees.md
 atomics_examples/
+
+# Build artifacts
 *.png
 *.jpg
 *.mp4
@@ -17,4 +24,10 @@ tmax
 prec
 Manifest.toml
 
+src/assets/syntaxtheme.css
+
+# Assets should be checked in
 !src/assets/*
+
+# except for this
+src/assets/syntaxtheme.css

docs/make.jl

@@ -116,6 +116,14 @@ srcpath = joinpath(docspath, "src")
 buildpath = joinpath(docspath, "build")
 mediapath = download_reference()
 
+################################################################################
+#                          Syntax highlighting theme                           #
+################################################################################
+
+@info("Writing highlighting stylesheet")
+open(joinpath(srcpath, "assets", "syntaxtheme.css"), "w") do io
+    MakieGallery.Highlights.stylesheet(io, MIME("text/css"), MakieGallery.DEFAULT_HIGHLIGHTER[])
+end
 
 ################################################################################
 #                      Automatic Markdown page generation                      #
@@ -278,7 +286,10 @@ makedocs(
     doctest = false, clean = true,
     format = Documenter.HTML(
         prettyurls = false,
-        assets = ["assets/favicon.ico"],
+        assets = [
+            "assets/favicon.ico",
+            "assets/syntaxtheme.css"
+        ],
     ),
     sitename = "Makie.jl",
     expandfirst = [

examples/diffeq.jl

@@ -106,6 +106,8 @@ end
         end
         scene = vbox(hbox(sσ, sρ, sβ, st, sr), three, parent = parent)
 
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
 
     end

examples/examples2d.jl

@@ -504,6 +504,8 @@
 
         linesegments!(scene, coords; visible = visible)
 
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
 
     end

examples/interactive.jl

@@ -45,10 +45,15 @@
         on(msize[end][:value]) do val
             p2.markersize = val
         end
-        RecordEvents(hbox(
+
+        final = hbox(
             vbox(b1, b2, msize),
             scene
-        ), @replace_with_a_path)
+        )
+
+        # Do not execute beyond this point!
+
+        RecordEvents(final, @replace_with_a_path)
     end
 
     @cell "Mouse Picking" [scatter, heatmap, interactive] begin
@@ -64,6 +69,9 @@
            return
         end
         scatter!(scene, clicks, color = :red, marker = '+', markersize = 10)
+
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
     end
 
@@ -77,10 +85,11 @@
         end
         p = scatter(data, markersize = s1[end][:value])
 
-        RecordEvents(
-            hbox(p, vbox(s1, s2), parent = Scene(resolution = (500, 500))),
-            @replace_with_a_path
-        )
+        final = hbox(p, vbox(s1, s2), parent = Scene(resolution = (500, 500)))
+
+        # Do not execute beyond this point!
+
+        RecordEvents(final, @replace_with_a_path)
     end
 
     @cell "Mouse Hover" [lines, hover, lift, poly, translate, text, popup, on] begin
@@ -114,6 +123,9 @@
             end
             return
         end
+
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
     end
 
@@ -162,6 +174,9 @@
             hbox(s1, s2, s3, s4, s5, s6),
             mesh_scene, parent = parent
         )
+
+        # Do not execute beyond this point!
+
         RecordEvents(parent, @replace_with_a_path)
     end
 
@@ -214,6 +229,9 @@
         add_move!(scene, points, pplot)
         add_remove_add!(scene, points, pplot)
         center!(scene)
+
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
     end
 
@@ -249,6 +267,9 @@
         red_clicks = scene[end]
         scatter!(scene, t, blues, color = :blue, marker = 'o')
         center!(scene)
+
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
     end
     @cell "Orbit Diagram" [scatter, slider] begin
@@ -297,6 +318,9 @@
             p,
             vbox(r1, r2)
         )
+
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
     end
 
@@ -397,6 +421,9 @@
         update_cam!(s, Vec3f0(7.0, 4.0, 6.0), Vec3f0(6.0, 2.5, 4.5))
         parent = Scene(resolution = (1000, 500))
         vbox(hbox(sliders...), s, parent = parent)
+
+        # Do not execute beyond this point!
+
         RecordEvents(parent, @replace_with_a_path)
     end
 
@@ -545,6 +572,9 @@
         universe.center = false
         task = @async spin(universe, orbit_speed, scale, moon, earth, ships)
         scene.center = false
+
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
     end
 
@@ -592,6 +622,9 @@
                 sleep(0.001)
             end
         end
+
+        # Do not execute beyond this point!
+
         RecordEvents(S, @replace_with_a_path);
     end
 
@@ -654,6 +687,9 @@
                 contour(volume, alpha = 0.1, levels = 10)
             )
         )
+
+        # Do not execute beyond this point!
+
         RecordEvents(scene, @replace_with_a_path)
     end
 end

examples/videoplayer.jl

@@ -207,7 +207,7 @@
                 lastmpos[] = mouseposition(scene)
             end
         end
-
+        # Do not execute beyond this point!
         RecordEvents(scene, @replace_with_a_path(mp4))
     end
 

src/documenter_extension.jl

@@ -1,3 +1,6 @@
+"The syntax highlighter to use when embedding plots."
+const DEFAULT_HIGHLIGHTER = Ref(Highlights.Themes.DefaultTheme)
+
 struct DatabaseLookup <: Expanders.ExpanderPipeline end
 
 Selectors.order(::Type{DatabaseLookup}) = 0.5
@@ -30,7 +33,7 @@ function look_up_source(database_key)
     end
 end
 
-function Selectors.runner(::Type{DatabaseLookup}, x, page, doc)
+function basic_example_embed(::Type{DatabaseLookup}, x, page, doc)
     matched = nothing
     for elem in x.content
         if isa(elem, AbstractString)
@@ -71,7 +74,10 @@ function Selectors.runner(::Type{DatabaseLookup}, x, page, doc)
             if subidx != nothing
                 source = split(source, "@substep", keepempty = false)[subidx]
             end
-            src_code = Markdown.MD(Markdown.Code("julia", source))
+            hio = IOBuffer(read = true, write = true)
+            highlight(hio, MIME("text/html"), source, Highlights.Lexers.JuliaLexer, DEFAULT_HIGHLIGHTER[])
+            html = String(take!(hio))
+            src_code = Documenter.Documents.RawHTML(html)
             push!(content, src_code)
         end
         # TODO figure out a better way to not hardcode this
@@ -186,3 +192,114 @@ function get_video_duration(path::AbstractString)
         dur = 0.5
     end
 end
+
+function cell_example_embed(::Type{DatabaseLookup}, x, page, doc)
+
+    matched = nothing
+    for elem in x.content
+        if isa(elem, AbstractString)
+            matched = match(regex_pattern, elem)
+            matched != nothing && break
+        end
+    end
+    matched == nothing && error("No match: $x")
+    capture = matched[1]
+    embed = matched[2]
+
+    subidx = nothing
+    # we also allow to reference a subsection annotated with @substep with an
+    # inter: @example_database("Title", 2)
+    if embed isa AbstractString && all(isnumeric, embed)
+        subidx = parse(Int, embed)
+        embed = nothing
+    end
+    # The sandboxed module -- either a new one or a cached one from this page.
+    database_keys = lowercase.(filter(x-> !(x in ("", " ")), split(capture, '"')))
+    # info("$database_keys with embed option $embed")
+    map(database_keys) do database_key
+        is_stepper = false
+
+        # buffer for content
+        content = []
+
+        # bibliographic stuff
+        idx = findall(x-> lowercase(x.title) == database_key, database)
+        isempty(idx) && error("can't find example $database_key")
+        entry = database[idx[1]]
+        uname = string(entry.unique_name)
+        lines = entry.file_range
+        tags = entry.tags
+        src_code = ""
+        # print source code for the example
+        if embed == nothing || isequal(embed, "code")
+            global src_code
+            source = look_up_source(database_key)
+            if subidx != nothing
+                source = split(source, "@substep", keepempty = false)[subidx]
+            end
+            hio = IOBuffer(read = true, write = true)
+            highlight(hio, MIME("text/html"), source, Highlights.Lexers.JuliaLexer, DEFAULT_HIGHLIGHTER[])
+            html = String(take!(hio))
+            src_code = Documenter.Documents.RawHTML(html)
+            push!(content, src_code)
+        end
+        # TODO figure out a better way to not hardcode this
+        media_root = ref_image_dir()
+        # embed plot for the example
+        if embed == nothing || isequal(embed, "plot")
+            # print to buffer
+            str = sprint() do io
+                mpath = joinpath(media_root, uname, "media")
+                if !isdir(mpath)
+                    @error("Can't find referenced example $(uname), with title: $(entry.title), with database query: $(capture)")
+                end
+                files = readdir(mpath)
+                if subidx !== nothing
+                    idx = findfirst(files) do file
+                        num = match(r"\d+", file)
+                        num === nothing && return false
+                        subidx == parse(Int, num.match)
+                    end
+                    if idx !== nothing
+                        embed_media(io, [master_url(media_root, joinpath(mpath, files[idx]))])
+                    end
+                else
+                    embed_media(io, master_url.(media_root, joinpath.(mpath, files)))
+                end
+            end
+
+            if embed == nothing
+                empty!(content)
+                push!(
+                    content,
+                    embed_into_cell(
+                        src_code.code, str
+                    )
+                )
+            else
+                # print code for embedding plot
+                src_plot = Documenter.Documents.RawHTML(str)
+                embed == "plot" || push!(content, src_plot)
+            end
+        end
+        # finally, map the content back to the page
+        page.mapping[x] = content
+    end
+end
+
+function embed_into_cell(source, media)
+    return Documenter.Documents.RawHTML("""
+    <div class="columns">
+        <div class="column is-half">
+            $source
+        </div>
+        <div class="column is-half">
+           $media
+        </div>
+    </div>
+    """)
+end
+
+# Alias this to whichever function we want to use (default to basic)
+
+Selectors.runner(::Type{DatabaseLookup}, x, page, doc) = basic_example_embed(DatabaseLookup, x, page, doc)