Merge pull request #33 from MakieOrg/jk/docs-fixes

Docs fixes

Author: jkrumbiegel

.github/workflows/CI.yml

@@ -55,7 +55,6 @@ jobs:
         shell: julia --project=docs --color=yes {0}
         run: |
           using Pkg
-          Pkg.develop(PackageSpec(path=pwd()))
           Pkg.instantiate()
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-docdeploy@v1

docs/Project.toml

@@ -6,10 +6,11 @@ CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
+Librsvg_jll = "925c91fb-5dd6-59dd-8e8c-345e74382d89"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-MakieTeX = "6d554a22-29e7-47bd-aee5-0c5f06619414"
-PalmerPenguins = "8b842266-38fa-440a-9b57-31493939ab85"
 RDatasets = "ce6b1742-4840-55fa-b093-852dadbb1d8b"
-Rsvg = "c4c386cf-5103-5370-be45-f3a111cca3b8"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 SwarmMakie = "0b1c068e-6a84-4e66-8136-5c95cafa83ed"
+
+[sources]
+SwarmMakie = {path = ".."}

docs/documenter_figure_block.jl

@@ -2,14 +2,8 @@ using SwarmMakie
 using Documenter, DocumenterVitepress, Literate
 using CairoMakie
 
-CairoMakie.activate!(type="svg", pt_per_unit = 1)
-
-include("documenter_figure_block.jl")
-
 DocMeta.setdocmeta!(SwarmMakie, :DocTestSetup, :(using SwarmMakie); recursive=true)
 
-ENV["DATADEPS_ALWAYS_ACCEPT"] = true
-
 # Now, we convert the source code to markdown files using Literate.jl
 source_path = joinpath(dirname(@__DIR__), "src")
 output_path = joinpath(@__DIR__, "src", "source")
@@ -30,10 +24,6 @@ function _add_meta_edit_link_generator(path)
     end
 end
 
-function _replace_example_with_figure(input)
-    return replace(input, "```@example" => "```@figure")
-end
-
 # First letter of `str` is made uppercase and returned
 ucfirst(str::String) = string(uppercase(str[1]), str[2:end])
 
@@ -49,7 +39,7 @@ function process_literate_recursive!(pages::Vector{Any}, path::String; source_pa
             Literate.markdown(
                 path, output_dir; 
                 flavor = Literate.CommonMarkFlavor(), 
-                postprocess = _add_meta_edit_link_generator(joinpath(relpath(source_path, output_dir), relative_path)) ∘ _replace_example_with_figure
+                postprocess = _add_meta_edit_link_generator(joinpath(relpath(source_path, output_dir), relative_path))
             )
             push!(pages, joinpath("source", splitext(relative_path)[1] * ".md"))
         end
@@ -65,7 +55,9 @@ withenv("JULIA_DEBUG" => "Literate") do # allow Literate debug output to escape
 end
 
 # As a special case, literatify the examples.jl file in docs/src to Documenter markdown
-Literate.markdown(joinpath(@__DIR__, "src", "examples", "examples.jl"), joinpath(@__DIR__, "src", "examples"); flavor = Literate.DocumenterFlavor(), postprocess = _replace_example_with_figure)
+Literate.markdown(joinpath(@__DIR__, "src", "examples", "examples.jl"), joinpath(@__DIR__, "src", "examples"); flavor = Literate.DocumenterFlavor())
+
+is_ci() = get(ENV, "CI", "false") == "true"
 
 makedocs(;
     modules=[SwarmMakie],
@@ -75,6 +67,7 @@ makedocs(;
         repo = "https://github.com/MakieOrg/SwarmMakie.jl",
         devurl = "dev",
         devbranch = "main",
+        (is_ci() ? (;) : (; deploy_url = ""))..., # without deploy_url="" locally the build is broken due to a SwarmMakie.jl prefix
     ),
     pages=[
         "Introduction" => "introduction.md",
@@ -88,7 +81,7 @@ makedocs(;
         "API Reference" => "api.md",
         "Source code" => literate_pages,
     ],
-    warnonly = true,
+    warnonly = !is_ci(),
 )
 
 deploydocs(;

docs/make.jl

@@ -10,7 +10,7 @@ In addition, SwarmMakie offers jittered scatter plots as algorithms to `beeswarm
 
 Here's a comparison of all the available algorithms:
 
-```@figure all_algorithms
+```@example all_algorithms
 using SwarmMakie, CairoMakie
 algorithms = [NoBeeswarm() SimpleBeeswarm() WilkinsonBeeswarm(); UniformJitter() PseudorandomJitter() QuasirandomJitter()]
 fig = Figure(; size = (800, 450))
@@ -27,6 +27,7 @@ fig
 
 ```@docs; canonical=false
 SimpleBeeswarm
+SimpleBeeswarm2
 WilkinsonBeeswarm
 NoBeeswarm
 ```

docs/src/algorithms.md

@@ -17,12 +17,10 @@ fig
 # ## Palmer Penguins
 
 using AlgebraOfGraphics, CairoMakie, SwarmMakie
-using PalmerPenguins, DataFrames
 
-penguins = dropmissing(DataFrame(PalmerPenguins.load()))
-
-f = data(penguins) * mapping(:species, :bill_depth_mm, color=:sex) * visual(Beeswarm) |> draw
-f
+data(AlgebraOfGraphics.penguins()) *
+    mapping(:species, :bill_depth_mm, color=:sex) *
+    visual(Beeswarm) |> draw
 
 # ## SwarmMakie logo
 

docs/src/assets/logo.png

@@ -4,7 +4,7 @@ Beeswarm plots can be plotted in any combination of `xscale` and `yscale`.
 
 Specifically, beeswarm plots are correct in any [separable transform](https://geo.makie.org/stable/nonlinear_transforms/#Nonlinear-but-separable) - basically, any transform in which the x and y coordinates are independent of each other.  This excludes most geographic transformations, but includes any transformation you can make using `xscale` and `yscale` in a Makie `Axis`.
 
-```@figure logscale
+```@example logscale
 using SwarmMakie, CairoMakie
 data = randn(75) .+ 3
 fig = Figure()
@@ -17,7 +17,7 @@ fig
 
 Note how the shape of the beeswarm is transformed in the left plot, because of the log scale.
 
-```@figure logscale
+```@example logscale
 ax2.xscale = Makie.pseudolog10
 ax2.title = "Log x and y axes"
 fig

docs/src/examples/examples.jl

@@ -10,7 +10,7 @@ You can use swarm plots to simply separate scatter markers which share the same
 using Base.MathConstants
 using CSV
 using DataFrames
-using AlgebraOfGraphics, SwarmMakie, CairoMakie, MakieTeX
+using AlgebraOfGraphics, SwarmMakie, CairoMakie
 using StatsBase, CategoricalArrays
 
 # Load benchmark data from file
@@ -149,21 +149,34 @@ f
 ```@example julia-benchmark
 # Get logos for programming languages
 
-using Rsvg
 using CairoMakie
-using CairoMakie.Cairo, CairoMakie.FileIO
-using MakieTeX
+using CairoMakie.FileIO
+using Librsvg_jll
+
+function svg_to_img(svg)
+    mktempdir() do dir
+        pngpath = joinpath(dir, "img.png")
+        Librsvg_jll.rsvg_convert() do bin
+            open(`$bin -o $pngpath`, "w") do io
+                write(io, svg)
+            end
+        end
+        FileIO.load(pngpath)
+    end
+end
 
 language_logo_url(lang::String) = "https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/$(lowercase(lang))/$(lowercase(lang))-original.svg"
 
+language_to_img(lang::String) = svg_to_img(read(download(language_logo_url(lang)), String))
+
 language_marker_dict = Dict{String, Any}(
-    [key => read(download(language_logo_url(key)), String) |> MakieTeX.CachedSVG for key in ("c", "fortran", "go", "java", "javascript", "julia", "matlab", "python", "r", "rust")]
+    [key => language_to_img(key) for key in ("c", "fortran", "go", "java", "javascript", "julia", "matlab", "python", "r", "rust")]
 )
 
 language_marker_dict["octave"] = FileIO.load(File{format"PNG"}(download("https://upload.wikimedia.org/wikipedia/commons/thumb/6/6a/Gnu-octave-logo.svg/2048px-Gnu-octave-logo.svg.png"))) .|> Makie.Colors.ARGB32  
 
-language_marker_dict["luajit"] = read(download(language_logo_url("lua")), String) |> MakieTeX.CachedSVG
-language_marker_dict["mathematica"] = read(download("https://upload.wikimedia.org/wikipedia/commons/2/20/Mathematica_Logo.svg"), String) |> MakieTeX.CachedSVG
+language_marker_dict["luajit"] = language_to_img("lua")
+language_marker_dict["mathematica"] = read(download("https://upload.wikimedia.org/wikipedia/commons/2/20/Mathematica_Logo.svg"), String) |> svg_to_img
 
 
 f, a, p = beeswarm(
@@ -172,7 +185,7 @@ f, a, p = beeswarm(
     markersize = 11,
     axis = (;
         yscale = log10,
-        xticklabelrotation = 0, 
+        xticklabelrotation = pi/8, 
         xticklabelsize = 12,
         xticksvisible = false,
         topspinecolor = :gray,

docs/src/examples/scales.md

@@ -1,6 +1,6 @@
 # Gutters
 
-```@figure gutters; backend=:CairoMakie; type="svg" 
+```@example gutters; backend=:CairoMakie; type="svg" 
 using SwarmMakie, CairoMakie
 xs = rand(1:10, 2000)
 beeswarm(xs, rand(2000); gutter = 0.3, color = xs)
@@ -14,7 +14,7 @@ A nice gutter size to avoid overlap in neighboring categories ranges between `0.
 
 ## Examples
 
-```@figure gutters
+```@example gutters
 using SwarmMakie, CairoMakie
 f, a, p = beeswarm(
     rand(1:3, 300), randn(300); 
@@ -23,7 +23,7 @@ f, a, p = beeswarm(
 p.gutter = 0.5
 ```
 Note the warning messages printed here!  These can be helpful to diagnose when your data is moving too far out of the gutter, but you can turn them off by passing `gutter_threshold = false` or setting the `gutter_threshold` to a higher value (must be an `Int` and >0).
-```@figure gutters
+```@example gutters
 f
 ```