move plotting function and layoutables docs into separate files (#659)

* move plotting function docs into separate files

* join paths

* path fix

* another try

* fixes

* titles

* change examples to cairomakie

* more plotting functions changed to cairomakie, activate glmakie

* more changes

* bug

* shift layoutables into their own files

* layoutables examples get own pages, some more cairomakie

* return scene

* fix

* generic page for layoutables

* add small example of figure vs layoutscene

* fix ref

* dot

* bbox example

* use 1.5.3

* Update docs.yml

* activate glmakie in lighting docs

Co-authored-by: Simon <[email protected]>

docs/make.jl

@@ -341,27 +341,43 @@ makedocs(
         ],
     ),
     sitename = "Makie Plotting Ecosystem",
-    expandfirst = [
-        "plotting_functions.md",
-    ],
     pages = Any[
         "Home" => "index.md",
         "Basics" => [
             "Basic Tutorial" => "basic-tutorial.md",
             "Layout Tutorial" => "makielayout/tutorial.md",
             "animation.md",
             "interaction.md",
-            "plotting_functions.md",
+            "Plotting Functions" =>
+                joinpath.(
+                    "plotting_functions",
+                    filter(
+                        endswith(".md"),
+                        readdir(joinpath(srcpath, "plotting_functions"),
+                            sort = true)
+                    )
+                ),
             "theming.md",
         ],
         "Documentation" => [
             "plot_method_signatures.md",
             "Figure" => "figure.md",
-            "Axis" => "makielayout/laxis.md",
-            "GridLayout" => "makielayout/grids.md",
-            "Legend" => "makielayout/llegend.md",
-            "Layoutables & Widgets" => "makielayout/layoutables_examples.md",
-            "How Layouting Works" => "makielayout/layouting.md",
+            "Layoutables & Widgets" => [
+                "makielayout/layoutables.md",
+                "makielayout/axis.md",
+                "makielayout/box.md",
+                "makielayout/button.md",
+                "makielayout/colorbar.md",
+                "makielayout/gridlayout.md",
+                "makielayout/label.md",
+                "makielayout/legend.md",
+                "makielayout/lscene.md",
+                "makielayout/menu.md",
+                "makielayout/slider.md",
+                "makielayout/toggle.md",
+
+            ],
+            "makielayout/layouting.md",
             "generated/colors.md",
             "generated/plot-attributes.md",
             "recipes.md",

docs/src/animation.md

@@ -19,6 +19,7 @@ As a start, here is how you can change the color of a line plot:
 
 ```@example 1
 using GLMakie
+GLMakie.activate!() # hide
 using AbstractPlotting.Colors
 
 figure, ax, lineplot = lines(0..10, sin; linewidth=10)

docs/src/basic-tutorial.md

@@ -8,6 +8,7 @@ Otherwise, an interactive window will open when you return a `Figure`.
 
 ```@example 1
 using GLMakie
+GLMakie.activate!() # hide
 AbstractPlotting.inline!(true)
 nothing # hide
 ```

docs/src/figure.md

@@ -56,9 +56,10 @@ If you index into the figure, a `FigurePosition` object that stores this indexin
 This object can be used to plot a new axis into a certain layout position in the figure, for example like this:
 
 ```@example
-using GLMakie
+using CairoMakie
+CairoMakie.activate!() # hide
 
-f = Figure()
+f = Figure(resolution = (800, 600))
 pos = f[1, 1]
 scatter(pos, rand(100, 2))
 
@@ -69,23 +70,33 @@ lines(pos2, cumsum(randn(100)))
 heatmap(f[1, 3], randn(10, 10))
 
 f
+save("figurepositions.svg", f); nothing # hide
 ```
 
+![figurepositions](figurepositions.svg)
+
 You can also index further into a `FigurePosition`, which creates a `FigureSubposition`.
 With `FigureSubposition`s you can describe positions in arbitrarily nested grid layouts.
 Often, a desired plot layout can only be achieved with nesting, and repeatedly indexing makes this easy.
 
 ```@example
-using GLMakie
+using CairoMakie
+CairoMakie.activate!() # hide
+
+f = Figure(resolution = (800, 600))
 
-f = Figure()
 f[1, 1] = Axis(f, title = "I'm not nested")
 f[1, 2][1, 1] = Axis(f, title = "I'm nested")
+
 # plotting into nested positions also works
 heatmap(f[1, 2][2, 1], randn(20, 20))
+
 f
+save("figurepositions_2.svg", f); nothing # hide
 ```
 
+![figurepositions_2](figurepositions_2.svg)
+
 All nested grid layouts that don't exist yet, but are needed for a nested plotting call, are created in the background automatically.
 
 !!! note

docs/src/index.md

@@ -27,7 +27,6 @@ CairoMakie.activate!()
 
 - Learn the basics of plotting with Makie in the [Basic Tutorial](@ref)
 - Check out how to make more complex plots and layouts in the [Layout Tutorial](@ref)
-- See examples of many plotting functions under [Plotting Functions](@ref).
 
 ```@eval
 using Markdown

docs/src/interaction.md

@@ -221,7 +221,7 @@ end
 
 ## Interactive Widgets
 
-Makie has a couple of useful interactive widgets like sliders, buttons and menus, which you can read about in the [Layoutables & Widgets](@ref) section.
+Makie has a couple of useful interactive widgets like sliders, buttons and menus, which you can read about in the [Layoutables](@ref) section.
 
 ## Recording Animations with Interactions
 

docs/src/lighting.md

@@ -37,6 +37,7 @@ A matcap (material capture) is a texture which is applied based on the normals o
 
 ```@example 1
 using GLMakie
+GLMakie.activate!() # hide
 using AbstractPlotting
 xs = -10:0.1:10
 ys = -10:0.1:10
@@ -64,6 +65,7 @@ scene
 
 ```@example 1
 using GLMakie
+GLMakie.activate!() # hide
 GLMakie.enable_SSAO[] = true
 close(GLMakie.global_gl_screen()) # close any open screen
 
@@ -86,7 +88,9 @@ scene
 ```
 
 ```@example 1
-using FileIO, GLMakie
+using FileIO
+using GLMakie
+GLMakie.activate!() # hide
 catmesh = FileIO.load(GLMakie.assetpath("cat.obj"))
 gold = FileIO.load(download("https://raw.githubusercontent.com/nidorx/matcaps/master/1024/E6BF3C_5A4719_977726_FCFC82.png"))
 

docs/src/makielayout/laxis.md → docs/src/makielayout/axis.md

@@ -3,6 +3,8 @@ using CairoMakie
 CairoMakie.activate!(type = "png")
 ```
 
+# Axis
+
 ## Creating an Axis
 
 The `Axis` is a 2D axis that works well with automatic layouts.

docs/src/makielayout/box.md

@@ -0,0 +1,24 @@
+```@eval
+using CairoMakie
+CairoMakie.activate!()
+```
+
+# Box
+
+A simple rectangle poly that is layoutable. This can be useful to make boxes for
+facet plots or when a rectangular placeholder is needed.
+
+```@example
+using CairoMakie
+using ColorSchemes
+
+fig = Figure(resolution = (1200, 900))
+
+rects = fig[1:4, 1:6] = [
+    Box(fig, color = c)
+    for c in get.(Ref(ColorSchemes.rainbow), (0:23) ./ 23)]
+
+save("example_lrect.svg", fig); nothing # hide
+```
+
+![example lrect](example_lrect.svg)

docs/src/makielayout/button.md

@@ -0,0 +1,29 @@
+```@eval
+using CairoMakie
+CairoMakie.activate!()
+```
+
+# Button
+
+```@example
+using CairoMakie
+
+fig = Figure(resolution = (1200, 900))
+
+Axis(fig[1, 1])
+fig[2, 1] = buttongrid = GridLayout(tellwidth = false)
+
+buttons = buttongrid[1, 1:5] = [Button(fig, label = "Button $i") for i in 1:5]
+
+for button in buttons
+    on(button.clicks) do n
+        println("$(button.label[]) was clicked $n times.")
+    end
+end
+
+fig
+
+save("example_lbutton.svg", fig); nothing # hide
+```
+
+![example lbutton](example_lbutton.svg)

docs/src/makielayout/colorbar.md

@@ -0,0 +1,76 @@
+```@eval
+using CairoMakie
+CairoMakie.activate!()
+```
+
+# Colorbar
+
+A Colorbar needs a colormap and a tuple of low/high limits.
+The colormap's axis will then span from low to high along the visual representation of the colormap.
+You can set ticks in a similar way to `Axis`.
+
+Here's how you can create Colorbars manually.
+
+```@example
+using CairoMakie
+
+fig = Figure(resolution = (1200, 900))
+
+Axis(fig[1, 1])
+
+# vertical colorbars
+Colorbar(fig[1, 2], width = 25, limits = (0, 10), colormap = :viridis,
+    flipaxis = false)
+Colorbar(fig[1, 3], width = 25, limits = (0, 5),
+colormap = cgrad(:Spectral, 5, categorical = true))
+Colorbar(fig[1, 4], width = 25, limits = (-1, 1), colormap = :heat,
+    highclip = :cyan, lowclip = :red, label = "Temperature")
+
+# horizontal colorbars
+Colorbar(fig[2, 1], height = 25, limits = (0, 10), colormap = :viridis,
+    vertical = false)
+Colorbar(fig[3, 1], height = 25, limits = (0, 5),
+    colormap = cgrad(:Spectral, 5, categorical = true), vertical = false)
+Colorbar(fig[4, 1], height = 25, limits = (-1, 1), colormap = :heat,
+    label = "Temperature", vertical = false, flipaxis = false,
+    highclip = :cyan, lowclip = :red)
+
+fig
+
+save("example_colorbar.svg", fig); nothing # hide
+```
+
+![example colorbar](example_colorbar.svg)
+
+You can also automatically choose colormap and limits for certain plot objects by passing them as the second argument.
+
+```@example
+using CairoMakie
+
+xs = LinRange(0, 20, 50)
+ys = LinRange(0, 15, 50)
+zs = [cos(x) * sin(y) for x in xs, y in ys]
+
+fig = Figure(resolution = (1200, 900))
+
+ax, hm = heatmap(fig[1, 1][1, 1], xs, ys, zs)
+Colorbar(fig[1, 1][1, 2], hm, width = 20)
+
+ax, hm = heatmap(fig[1, 2][1, 1], xs, ys, zs, colormap = :grays,
+    colorrange = (-0.75, 0.75), highclip = :red, lowclip = :blue)
+Colorbar(fig[1, 2][1, 2], hm, width = 20)
+
+ax, hm = contourf(fig[2, 1][1, 1], xs, ys, zs,
+    levels = -1:0.25:1, colormap = :heat)
+Colorbar(fig[2, 1][1, 2], hm, width = 20, ticks = -1:0.25:1)
+
+ax, hm = contourf(fig[2, 2][1, 1], xs, ys, zs,
+    colormap = :Spectral, levels = [-1, -0.5, -0.25, 0, 0.25, 0.5, 1])
+Colorbar(fig[2, 2][1, 2], hm, width = 20, ticks = -1:0.25:1)
+
+fig
+save("example_colorbar_2.svg", fig); nothing # hide
+```
+
+![example colorbar 2](example_colorbar_2.svg)
+

docs/src/makielayout/grids.md → docs/src/makielayout/gridlayout.md

@@ -3,6 +3,8 @@ using CairoMakie
 CairoMakie.activate!()
 ```
 
+# GridLayout
+
 ## Setting column and row sizes correctly
 
 There are four different types of sizes you can give rows and columns.

docs/src/makielayout/label.md

@@ -0,0 +1,26 @@
+```@eval
+using CairoMakie
+CairoMakie.activate!()
+```
+
+# Label
+
+This is just normal text, except it's also layoutable. A text's size is known,
+so rows and columns in a GridLayout can shrink to the appropriate width or height.
+
+```@example
+using CairoMakie
+
+fig = Figure(resolution = (1200, 900))
+
+fig[1:2, 1:3] = [Axis(fig) for _ in 1:6]
+
+supertitle = Label(fig[0, :], "Six plots", textsize = 30)
+
+sideinfo = Label(fig[2:3, 0], "This text is vertical", rotation = pi/2)
+
+save("example_ltext.svg", fig); nothing # hide
+```
+
+![example ltext](example_ltext.svg)
+