Gallery improvements (#257)

* Add GeoInterfaceMakie as well

* Add a build stage that moves cardmeta to the bottom of the doc

* Document the cardmeta stage

* Move basic's cardmeta block to the top

* Switch to julia-docdeploy again

* Packageify the gallery code

* add the Project.toml and load

* Fix action

* Dont include gallery setup since its useless

* import gallery dict

* allow a Tags attr too

* use Makie

.github/workflows/ci.yml

@@ -81,11 +81,13 @@ jobs:
           DISPLAY: ':0'
           DATADEPS_ALWAYS_ACCEPT: 'true'
           RASTERDATASOURCES_PATH: '~/.julia/artifacts/RasterDataSources'
-      - name: Build and deploy
+      - uses: julia-actions/julia-docdeploy@v1
+        with:
+          prefix: xvfb-run
+          install-package: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
           DISPLAY: ':0'
           DATADEPS_ALWAYS_ACCEPT: 'true'
           RASTERDATASOURCES_PATH: '~/.julia/artifacts/RasterDataSources'
-        run: xvfb-run -s '-screen 0 1024x768x24' julia --project=docs/ docs/make.jl deploy

.gitignore

@@ -22,3 +22,5 @@ docs/build/
 node_modules/
 docs/package-lock.json
 test_images/
+
+docs/GeoMakieDocumenterBlocks/Manifest.toml

Project.toml

@@ -8,6 +8,7 @@ Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 GeoFormatTypes = "68eda718-8dee-11e9-39e7-89f7f65f511f"
 GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
+GeoInterfaceMakie = "0edc0954-3250-4c18-859d-ec71c1660c08"
 GeoJSON = "61d90e0f-e114-555e-ac52-39dfb47a3ef9"
 Geodesy = "0ef565a4-170c-5f04-8de2-149903a85f3d"
 GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
@@ -26,6 +27,7 @@ Colors = "0.12"
 Downloads = "1"
 GeoFormatTypes = "0.4"
 GeoInterface = "0.5, 1.0"
+GeoInterfaceMakie = "0.1.6"
 GeoJSON = "0.6, 0.7, 0.8"
 Geodesy = "1.1.0"
 GeometryBasics = "0.4.11"

docs/GeoMakieDocumenterBlocks/Project.toml

@@ -0,0 +1,9 @@
+[deps]
+Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
+ImageTransformations = "02fcd773-0e25-5acc-982a-7f6622650795"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"

docs/GeoMakieDocumenterBlocks/src/GeoMakieDocumenterBlocks.jl

@@ -0,0 +1,15 @@
+module GeoMakieDocumenterBlocks
+
+using Documenter
+using ImageTransformations, ImageIO, Base64, FileIO # for resize
+import Documenter: MarkdownAST
+using Makie
+
+const GALLERY_DICT = Dict{String, Any}()
+
+export GALLERY_DICT
+
+include("cardmeta.jl")
+include("overview.jl")
+
+end

docs/blocks/cardmeta.jl → docs/GeoMakieDocumenterBlocks/src/cardmeta.jl

@@ -1,3 +1,16 @@
+#=
+# The `cardmeta` pipeline
+
+Cardmeta blocks add metadata to a demo file.  
+
+The pipeline has two parts:
+- The actual cardmeta block which moves things around
+- The initial transformer which moves all cardmeta blocks to the end of the page
+
+The reason we need to move the block to the end is so that it is evaluated
+after all other blocks in the page.
+=#
+
 using Documenter
 using ImageTransformations, ImageIO, Base64, FileIO # for resize
 import Documenter: MarkdownAST
@@ -40,7 +53,7 @@ function Documenter.Selectors.runner(::Type{CardMetaBlocks}, node, page, doc)
         # wants to hide. We should probably warn, but it is common enough that
         # we will silently skip for now.
         if Documenter.isassign(ex)
-            if !(ex.args[1] in (:Title, :Description, :Cover, :Authors, :Date))
+            if !(ex.args[1] in (:Title, :Description, :Cover, :Authors, :Date, :Tags))
                 source = Documenter.locrepr(page.source, lines)
                 @warn(
                     "In $source: `@cardmeta` block has an unsupported " *
@@ -99,6 +112,7 @@ function Documenter.Selectors.runner(::Type{CardMetaBlocks}, node, page, doc)
                     rethrow(e)
                 end
             end
+
             if contents isa Makie.FigureLike
                 meta[:Cover] = contents
                 break
@@ -141,3 +155,28 @@ function set_cover_to_png!(meta, page, doc)
         meta[:Cover] = "/" * joinpath(relpath(page.workdir, doc.user.build), filename)
     end
 end
+
+
+
+abstract type MoveCardMeta <: Documenter.Builder.DocumentPipeline end
+
+Documenter.Selectors.order(::Type{MoveCardMeta}) = 1.2 # after doctest, before expand templates.
+
+function _is_cardmeta_block(x)
+    return x.element isa MarkdownAST.CodeBlock && Base.occursin("@cardmeta", x.element.info)
+end
+
+function Documenter.Selectors.runner(::Type{MoveCardMeta}, doc::Documenter.Document)
+    # Main.@infiltrate
+    for (filename, page) in doc.blueprint.pages
+        cardmeta_blocks = filter(_is_cardmeta_block, collect(page.mdast.children))
+        if !isempty(cardmeta_blocks) # some cardmeta block was detected
+            # move the cardmeta block from wherever it is to the end of the page.
+            MarkdownAST.insert_after!(last(page.mdast.children), first(cardmeta_blocks))
+        elseif Base.occursin("examples", splitdir(page.build)[1]) # only inject cardmeta if in examples dir
+            # do nothing for now - potentially inject an extra cardmeta block at the end
+            # of every page.
+            MarkdownAST.insert_after!(last(page.mdast.children), MarkdownAST.@ast MarkdownAST.CodeBlock("@cardmeta", ""))
+        end
+    end
+end

docs/blocks/overview.jl → docs/GeoMakieDocumenterBlocks/src/overview.jl

@@ -9,12 +9,10 @@ abstract type OverviewGalleryBlocks <: Documenter.Expanders.ExpanderPipeline end
 Documenter.Selectors.order(::Type{OverviewGalleryBlocks}) = 12.0
 Documenter.Selectors.matcher(::Type{OverviewGalleryBlocks}, node, page, doc) = Documenter.iscode(node, r"^@overviewgallery")
 
-GALLERY_DICT = Dict{String, Any}()
-
 function Documenter.Selectors.runner(::Type{OverviewGalleryBlocks}, node, page, doc)
     @assert node.element isa MarkdownAST.CodeBlock
     x = node.element
-    @assert contains(x.info, "@overviewgallery")
+    @assert Base.contains(x.info, "@overviewgallery")
     @assert !isempty(chomp(x.code)) "The `@overviewgallery` block must have at least one page name."
     # Main.@infiltrate
     # Bail early if in draft mode

docs/make.jl

@@ -1,17 +1,16 @@
 using Documenter, DocumenterVitepress, Literate
 using GeoMakie, CairoMakie, Makie, GeoInterfaceMakie
 
-# some strategic imports
+# some strategic imports to avoid world age issues
 using FHist
 
-include("blocks/gallery_setup.jl")
-include("blocks/cardmeta.jl")
-include("blocks/overview.jl")
+include(joinpath(@__DIR__, "GeoMakieDocumenterBlocks", "src", "GeoMakieDocumenterBlocks.jl"))
+import .GeoMakieDocumenterBlocks: GALLERY_DICT
 # Set some global settings
 # Good quality CairoMakie with PNG
 CairoMakie.activate!(px_per_unit = 2, type = :png)
 # Rasters should download into the artifacts folder (so they can be cached :D)
-ENV["RASTERDATASOURCES_PATH"] = joinpath(first(Base.DEPOT_PATH), "artifacts")
+get!(ENV, "RASTERDATASOURCES_PATH", joinpath(first(Base.DEPOT_PATH), "artifacts"))
 # invoke some geomakie things to be sure it works
 GeoMakie.coastlines()
 GeoMakie.earth()

docs/src/adding_demos.md

@@ -14,7 +14,7 @@ Functional requirements are:
 - At each stage, return a `FigureLike`.
 
 
-When adding the code to save to `covers`, you must add the following code to the bottom of your Julia file:
+When adding the code to save to `covers`, you must add the following code to your Julia file:
 ````julia
 #=
 ```@cardmeta
@@ -28,11 +28,14 @@ assuming `fig` is the main figure of that example.
 
 Note that all of this code is commented out - this is important, otherwise Documenter.jl will not be able to pick it up.
 
-You can even pass a compound expression as `Cover = begin ... end` if you want to create a custom cover figure.  This will all be evaluated in the same scope as your example, but after all the code is executed.
+You can even pass a compound expression as `Cover = begin ... end` if you want to create a custom cover figure.  This will all be evaluated in the same scope as your example, but **after all the code is executed**.
 
 We also require that the comments in the file be of sufficient quantity and quality to explain what is going on to a newcomer.
 
 ## What is actually going on 
 
 In GeoMakie, we've created two custom Documenter blocks - `@cardmeta` and `@overviewgallery`.  The `@cardmeta` block adds metadata (cover image, title, description, etc) to a global dict.
+
 The `@overviewgallery` block retrieves this metadata and renders a grid of example cards in HTML, styled by the styles in `styles.css`.  
+
+There are two stages to the cardmeta pipeline.  First, we go through the document via a Documenter.jl build stage which is inserted after doctest, but before expand pipelines. This build stage parses each file for cardmeta, and if it is encountered, moves it to the absolute bottom of the file.  This means that when `ExpandTemplates` begins, it is guaranteed to execute cardmeta at the very end of the file.

examples/basic.jl

@@ -1,5 +1,13 @@
 # # Basic examples
 
+#=
+```@cardmeta
+Title = "Basic examples"
+Description = "Basic examples of GeoMakie"
+Cover = fig
+```
+=#
+
 using GeoMakie, CairoMakie # you could use GLMakie too
 
 lons = -180:180
@@ -33,9 +41,3 @@ scatter!(slons, slats; color = sfield)
 fig
 # Again, to save, run e.g. `save("scatter_example.png", fig; px_per_unit=2)`.
 #
-
-# ```@cardmeta
-# Title = "Basic examples"
-# Description = "Basic examples of GeoMakie"
-# Cover = fig
-# ```

src/GeoMakie.jl

@@ -28,6 +28,8 @@ using Geodesy
 using Proj
 import GeoFormatTypes
 
+import GeoInterfaceMakie # to activate GI geometry plotting
+
 export GeoInterface
 
 # bring in missing Makie methods required for block definition