fix docs on v2

JuliaPlots · Oct 13, 2024 · e52faa5 · e52faa5
1 parent fa63411
commit e52faa5
Show file tree

Hide file tree

Showing 20 changed files with 75 additions and 83 deletions.
diff --git a/PlotsBase/src/PlotsBase.jl b/PlotsBase/src/PlotsBase.jl
@@ -108,10 +108,6 @@ export
     test_examples,
     coords,
 
-    translate,
-    translate!,
-    rotate,
-    rotate!,
     center,
     plotattr,
     scalefontsizes,

diff --git a/docs/make.jl b/docs/make.jl
@@ -93,7 +93,7 @@ ref_name(i) = "ref" * lpad(i, 3, '0')
 
 function generate_cards(
     prefix::AbstractString, backend::Symbol, slice;
-    skip = get(Plots.PlotsBase._backend_skips, backend, Int[])
+    skip = get(PlotsBase._backend_skips, backend, Int[])
 )
     @show backend
     # create folder: for each backend we generate a DemoSection "generated" under "gallery"
@@ -102,7 +102,7 @@ function generate_cards(
 
     needs_rng_fix = Dict{Int,Bool}()
 
-    for (i, example) ∈ enumerate(Plots.PlotsBase._examples)
+    for (i, example) ∈ enumerate(PlotsBase._examples)
         (slice ≢ nothing && i ∉ slice) && continue
         # write out the header, description, code block, and image link
         jlname = "$backend-$(ref_name(i)).jl"
@@ -114,7 +114,7 @@ function generate_cards(
 
             # DemoCards YAML frontmatter
             # https://johnnychen94.github.io/DemoCards.jl/stable/quickstart/usage_example/julia_demos/1.julia_demo/#juliademocard_example
-            asset = if i ∈ Plots.PlotsBase._animation_examples
+            asset = if i ∈ PlotsBase._animation_examples
                 "anim_$(backend)_$(ref_name(i)).gif"
             else
                 "$(backend)_$(ref_name(i)).png"
@@ -151,14 +151,14 @@ function generate_cards(
         # DemoCards use Literate.jl syntax with extra leading `#` as markdown lines
         write(jl, "# $(replace(example.desc, "\n" => "\n  # "))\n")
         isnothing(example.imports) || pretty_print_expr(jl, example.imports)
-        needs_rng_fix[i] = (exprs_rng = Plots.PlotsBase.replace_rand(example.exprs)) != example.exprs
+        needs_rng_fix[i] = (exprs_rng = PlotsBase.replace_rand(example.exprs)) != example.exprs
         pretty_print_expr(jl, exprs_rng)
 
         # NOTE: the supported `Literate.jl` syntax is `#src` and `#hide` NOT `# src` !!
         # from the docs: """
         # #src and #hide are quite similar. The only difference is that #src lines are filtered out before execution (if execute=true) and #hide lines are filtered out after execution.
         # """
-        asset = if i ∈ Plots.PlotsBase._animation_examples
+        asset = if i ∈ PlotsBase._animation_examples
             "gif(anim, \"assets/anim_$(backend)_$(ref_name(i)).gif\")\n"  # NOTE: must not be hidden, for appearance in the rendered `html`
         else
             "png(\"assets/$(backend)_$(ref_name(i)).png\")  #src\n"
@@ -192,7 +192,7 @@ function generate_cards(
     # TODO(johnnychen): make this part of the page template
     attr_name = string(backend, ".jl")
     open(joinpath(cardspath, attr_name), "w") do jl
-        pkg = Plots.PlotsBase.backend_instance(Symbol(lowercase(string(backend))))
+        pkg = PlotsBase.backend_instance(Symbol(lowercase(string(backend))))
         write(jl, """
             # ---
             # title: Supported attribute values
@@ -202,10 +202,10 @@ function generate_cards(
             # date: $(now())
             # ---
 
-            # - Supported arguments: $(markdown_code_to_string(collect(Plots.PlotsBase.supported_attrs(pkg))))
-            # - Supported values for linetype: $(markdown_symbols_to_string(Plots.PlotsBase.supported_seriestypes(pkg)))
-            # - Supported values for linestyle: $(markdown_symbols_to_string(Plots.PlotsBase.supported_styles(pkg)))
-            # - Supported values for marker: $(markdown_symbols_to_string(Plots.PlotsBase.supported_markers(pkg)))
+            # - Supported arguments: $(markdown_code_to_string(collect(PlotsBase.supported_attrs(pkg))))
+            # - Supported values for linetype: $(markdown_symbols_to_string(PlotsBase.supported_seriestypes(pkg)))
+            # - Supported values for linestyle: $(markdown_symbols_to_string(PlotsBase.supported_styles(pkg)))
+            # - Supported values for marker: $(markdown_symbols_to_string(PlotsBase.supported_markers(pkg)))
             """
         )
     end
@@ -227,11 +227,11 @@ function make_support_df(allvals, func; default_backends)
     for be ∈ bs # cols
         be_supported_vals = fill("", length(vals))
         for (i, val) ∈ enumerate(vals)
-            be_supported_vals[i] = if func == Plots.PlotsBase.supported_seriestypes
-                stype = Plots.PlotsBase.seriestype_supported(Plots.PlotsBase.backend_instance(be), val)
+            be_supported_vals[i] = if func == PlotsBase.supported_seriestypes
+                stype = PlotsBase.seriestype_supported(PlotsBase.backend_instance(be), val)
                 stype ≡ :native ? "✅" : (stype ≡ :no ? "" : "🔼")
             else
-                val ∈ func(Plots.PlotsBase.backend_instance(be)) ? "✅" : ""
+                val ∈ func(PlotsBase.backend_instance(be)) ? "✅" : ""
             end
         end
         df[!, be] = be_supported_vals
@@ -241,10 +241,10 @@ end
 
 function generate_supported_markdown(; default_backends)
     supported_args = OrderedDict(
-        "Keyword Arguments" => (Plots.Commons._all_attrs, Plots.PlotsBase.supported_attrs),
-        "Markers" => (Plots.Commons._all_markers, Plots.PlotsBase.supported_markers),
-        "Line Styles" => (Plots.Commons._all_styles,  Plots.PlotsBase.supported_styles),
-        "Scales" => (Plots.Commons._all_scales,  Plots.PlotsBase.supported_scales)
+        "Keyword Arguments" => (Plots.Commons._all_attrs, PlotsBase.supported_attrs),
+        "Markers" => (Plots.Commons._all_markers, PlotsBase.supported_markers),
+        "Line Styles" => (Plots.Commons._all_styles,  PlotsBase.supported_styles),
+        "Scales" => (Plots.Commons._all_scales,  PlotsBase.supported_scales)
     )
     open(joinpath(GEN_DIR, "supported.md"), "w") do md
         write(md, """
@@ -260,7 +260,7 @@ function generate_supported_markdown(; default_backends)
             - 🔼 the series type is supported through series recipes.
 
             ```@raw html
-            $(to_html(make_support_df(Plots.PlotsBase.all_seriestypes(), Plots.PlotsBase.supported_seriestypes; default_backends)))
+            $(to_html(make_support_df(PlotsBase.all_seriestypes(), PlotsBase.supported_seriestypes; default_backends)))
             ```
             """
         )
@@ -289,7 +289,7 @@ function make_attr_df(ktype::Symbol, defs::KW)
         Description = fill("", n),
     )
     for (i, (k, def)) ∈ enumerate(defs)
-        type, desc = get(Plots.PlotsBase._arg_desc, k, (Any, ""))
+        type, desc = get(PlotsBase._arg_desc, k, (Any, ""))
 
         aliases = sort(collect(keys(filter(p -> p.second == k, Plots.Commons._keyAliases))))
         df.Attribute[i] = string(k)
@@ -585,12 +585,17 @@ function main()
     unicodeplots()
     gaston()
 
-    # NOTE: for a faster representative test build use `PLOTDOCS_BACKENDS='GR' PLOTDOCS_EXAMPLES='1'`
-    default_backends = "GR PythonPlot PlotlyJS PGFPlotsX UnicodePlots Gaston"
-    backends = get(ENV, "PLOTDOCS_BACKENDS", default_backends)
-    backends = backends == "ALL" ? default_backends : backends
+    # NOTE: for a faster representative test build use `PLOTDOCS_PACKAGES='GR' PLOTDOCS_EXAMPLES='1'`
+    default_packages = "GR,PythonPlot,PlotlyJS,PGFPlotsX,UnicodePlots,Gaston"
+    packages = get(ENV, "PLOTDOCS_PACKAGES", default_packages)
+    packages = let val = packages == "ALL" ? default_packages : packages
+        Symbol.(filter(!isempty, strip.(split(val, ","))))
+    end
+    packages_backends = NamedTuple(p => Symbol(lowercase(string(p))) for p ∈ packages)
+    backends = values(packages_backends) |> collect
+
+    @info "selected packages: $packages"
     @info "selected backends: $backends"
-    backends = Symbol.(lowercase.(split(backends)))
 
     slice = parse.(Int, split(get(ENV, "PLOTDOCS_EXAMPLES", "")))
     slice = length(slice) == 0 ? nothing : slice
@@ -606,21 +611,21 @@ function main()
 
     for (pkg, dest) ∈ (
             (PlotThemes, "plotthemes.md"),
-            # (StatsPlots, "statsplots.md"), #TODO: uncomment after having compatible StatsPlots
+            # (StatsPlots, "statsplots.md"), # TODO: uncomment after having compatible StatsPlots
         )
         cp(pkgdir(pkg, "README.md"), joinpath(GEN_DIR, dest); force = true)
     end
 
     @info "gallery"
     gallery = Pair{String,String}[]
     gallery_assets, gallery_callbacks, user_gallery = map(_ -> [], 1:3)
-    needs_rng_fix = Dict{String,Any}()
+    needs_rng_fix = Dict{Symbol,Any}()
 
-    for name ∈ backends
-        pname = string(Plots.PlotsBase.backend_package_name(name))
-        needs_rng_fix[pname] = generate_cards(joinpath(@__DIR__, "gallery"), name, slice)
-        let (path, cb, assets) = makedemos(joinpath("gallery", string(name)); src = "$work/gallery")
-            push!(gallery, pname => joinpath("gallery", path))
+    for pkg ∈ packages
+        be = packages_backends[pkg]
+        needs_rng_fix[pkg] = generate_cards(joinpath(@__DIR__, "gallery"), be, slice)
+        let (path, cb, assets) = makedemos(joinpath("gallery", string(be)); src = "$work/gallery")
+            push!(gallery, string(pkg) => joinpath("gallery", path))
             push!(gallery_callbacks, cb)
             push!(gallery_assets, assets)
         end
@@ -635,7 +640,7 @@ function main()
         "Getting Started" => [
             "Installation" => "install.md",
             "Basics" => "basics.md",
-            "Tutorial" => "tutorial.md",
+            # "Tutorial" => "tutorial.md",  # TODO: uncomment once StatsPlots is ready
             "Series Types" => [
                 "Contour Plots" => "series_types/contour.md",
                 "Histograms" => "series_types/histogram.md",
@@ -674,20 +679,20 @@ function main()
         "Learning" => "learning.md",
         "Contributing" => "contributing.md",
         "Ecosystem" => [
-            # "StatsPlots" => "generated/statsplots.md", #TODO: uncomment once StatsPlots is ready
+            # "StatsPlots" => "generated/statsplots.md",  # TODO: uncomment once StatsPlots is ready
             # "GraphRecipes" => [
             #     "Introduction" => "GraphRecipes/introduction.md",
             #     "Examples" => "GraphRecipes/examples.md",
             #     "Attributes" => "generated/graph_attributes.md",
-            # ], #TODO: uncomment once GraphRecipes is ready
+            # ], # TODO: uncomment once GraphRecipes is ready
             "UnitfulExt" => [
                 "Introduction" => "UnitfulExt/unitfulext.md",
                 "Examples" => [
                     "Simple" => "generated/unitfulext_examples.md",
                     "Plots" => "generated/unitfulext_plots.md",
                 ]
             ],
-            "Overview" => "ecosystem.md",
+            # "Overview" => "ecosystem.md",  # TODO: uncomment once StatsPlots is ready
         ],
         "Advanced Topics" => ["Plot objects" => "plot_objects.md","Plotting pipeline" => "pipeline.md"],
         "Gallery" => gallery,
@@ -708,8 +713,6 @@ function main()
     unique!(selected_pages)
     # @show selected_pages length(gallery) length(user_gallery)
 
-    # FIXME: github.com/JuliaDocs/DemoCards.jl/pull/134
-    # delete src/democards/bulmagridtheme.css when released
     n = 0
     for (root, dirs, files) ∈ walkdir(SRC_DIR)
         foreach(dir -> mkpath(joinpath(WORK_DIR, dir)), dirs)
@@ -770,9 +773,10 @@ function main()
     # postprocess gallery html files to remove `rng` in user displayed code
     # non-exhaustive list of examples to be fixed:
     # [1, 4, 5, 7:12, 14:21, 25:27, 29:30, 33:34, 36, 38:39, 41, 43, 45:46, 48, 52, 54, 62]
-    for name ∈ split(backends)
-        prefix = joinpath(@__DIR__, "build", "gallery", lowercase(name), "generated")
-        must_fix = needs_rng_fix[name]
+    for pkg ∈ packages
+        be = packages_backends[pkg]
+        prefix = joinpath(@__DIR__, "build", "gallery", string(be), "generated")
+        must_fix = needs_rng_fix[pkg]
         for file ∈ glob("*/index.html", prefix)
             (m = match(r"-ref(\d+)", file)) ≡ nothing && continue
             idx = parse(Int, first(m.captures))

diff --git a/docs/src/GraphRecipes/examples.md b/docs/src/GraphRecipes/examples.md
@@ -1,6 +1,6 @@
 ```@setup graphexamples
 using Plots, GraphRecipes, Graphs, LinearAlgebra, SparseArrays, AbstractTrees; gr()
-Plots.reset_defaults()
+Plots.Commons.reset_defaults()
 ```
 # [Examples](@id graph_examples)
 ### Undirected graph

diff --git a/docs/src/GraphRecipes/introduction.md b/docs/src/GraphRecipes/introduction.md
@@ -1,6 +1,6 @@
 ```@setup graphintro
 using Plots, GraphRecipes; gr()
-Plots.reset_defaults()
+Plots.Commons.reset_defaults()
 ```
 # GraphRecipes
 [GraphRecipes](https://github.com/JuliaPlots/GraphRecipes.jl) is a collection of recipes for visualizing graphs. Users specify a graph through an adjacency matrix, an adjacency list, or an `AbstractGraph` via [Graphs](https://github.com/JuliaGraphs/Graphs.jl). GraphRecipes will then use a layout algorithm to produce a visualization of the graph that the user passed.

diff --git a/docs/src/RecipesBase/types.md b/docs/src/RecipesBase/types.md
@@ -142,7 +142,7 @@ We can use this to define a user recipe for a pie plot.
         # determine the angle until we stop
         θ_new = θ + 2π * y[i] / s
         # calculate the coordinates
-        coords = [(0.0, 0.0); Plots.partialcircle(θ, θ_new, 50)]
+        coords = [(0.0, 0.0); PlotsBase.partialcircle(θ, θ_new, 50)]
         @series begin
             seriestype := :shape
             label --> string(labels[i])
@@ -307,7 +307,7 @@ However, the simpler approach is writing the pie recipe as a series recipe and r
     θ = 0
     for i in eachindex(y)
         θ_new = θ + 2π * y[i] / s
-        coords = [(0.0, 0.0); Plots.partialcircle(θ, θ_new, 50)]
+        coords = [(0.0, 0.0); PlotsBase.partialcircle(θ, θ_new, 50)]
         @series begin
             seriestype := :shape
             label --> string(x[i])
@@ -347,7 +347,7 @@ In fact, a pie recipe could be also implemented as a plot recipe by acessing the
     θ = 0
     for i in 1:length(y)
         θ_new = θ + 2π * y[i] / s
-        coords = [(0.0, 0.0); Plots.partialcircle(θ, θ_new, 50)]
+        coords = [(0.0, 0.0); PlotsBase.partialcircle(θ, θ_new, 50)]
         @series begin
             seriestype := :shape
             label --> string(labels[i])

diff --git a/docs/src/UnitfulExt/unitfulext_plots.jl b/docs/src/UnitfulExt/unitfulext_plots.jl
@@ -18,7 +18,7 @@ using Unitful, Plots
 
 # ## Lines
 
-plot(Plots.fakedata(50, 5) * u"m", w=3)
+plot(PlotsBase.fakedata(50, 5) * u"m", w=3)
 
 # ## Parametric plots
 
@@ -69,7 +69,7 @@ histogram2d(randn(10000) * u"cm", randn(10000) * u"cm", nbins=20)
 
 # ## Line styles
 
-styles = intersect([:solid, :dash, :dot, :dashdot, :dashdotdot], Plots.supported_styles())
+styles = intersect([:solid, :dash, :dot, :dashdot, :dashdotdot], PlotsBase.supported_styles())
 styles = reshape(styles, 1, length(styles))
 n = length(styles)
 y = cumsum(randn(20, n), dims=1) * u"km"
@@ -108,7 +108,7 @@ plot(
 
 # ## Marker types
 
-markers = intersect(Plots._shape_keys, Plots.supported_markers())
+markers = intersect(Plots._shape_keys, PlotsBase.supported_markers())
 markers = reshape(markers, 1, length(markers))
 n = length(markers)
 x = (range(0, stop=10, length=n + 2))[2:end - 1] * u"km"
@@ -130,7 +130,7 @@ plot(randn(100, 5) * u"km", layout=l, t=[:line :histogram :scatter :steppre :bar
 
 # ## Adding to subplots
 
-plot(Plots.fakedata(100, 10) * u"km", layout=4, palette=[:grays :blues :heat :lightrainbow], bg_inside=[:orange :pink :darkblue :black])
+plot(PlotsBase.fakedata(100, 10) * u"km", layout=4, palette=[:grays :blues :heat :lightrainbow], bg_inside=[:orange :pink :darkblue :black])
 
 # ## Contour plots
 

diff --git a/docs/src/animations.md b/docs/src/animations.md
@@ -1,6 +1,6 @@
 ```@setup animations
 using Plots; gr()
-Plots.reset_defaults()
+Plots.Commons.reset_defaults()
 ```
 
 ### [Animations](@id animations)

diff --git a/docs/src/backends.md b/docs/src/backends.md
@@ -1,6 +1,7 @@
 ```@setup backends
-using StatsPlots, RecipesBase, Statistics; gr()
-Plots.reset_defaults()
+# using StatsPlots  # NOTE: restore when StatsPlots compatible
+using Plots, RecipesBase, Statistics; gr()
+Plots.Commons.reset_defaults()
 
 @userplot BackendPlot
 
@@ -17,10 +18,13 @@ Plots.reset_defaults()
         [f g]
     end
 
+    #=
+    # NOTE: restore when StatsPlots compatible
     @series begin
         subplot := 2 + (n > 2)
         RecipesBase.recipetype(:groupedbar, d)
     end
+    =#
 
     if n > 2
         @series begin
@@ -133,7 +137,7 @@ Also, PlotlyJS supports saving the output to more formats than Plotly, such as E
 
 ```@example backends
 plotlyjs(); backendplot(n = 2)  #hide
-png("backends_plotlyjs.png")  #hide
+png("backends_plotlyjs.png")  #hide=#
 ```
 ![](backends_plotlyjs.png)
 
@@ -181,7 +185,7 @@ plot(
         :xaxis => KW(:domain => "auto")
    ),
 )
-Plots.html("plotly_mathjax")  #hide
+PlotsBase.html("plotly_mathjax")  #hide
 ```
 ```@raw html
 <object type="text/html" data="plotly_mathjax.html" style="width:100%;height:450px;"></object>

diff --git a/docs/src/colorschemes.md b/docs/src/colorschemes.md
@@ -1,6 +1,6 @@
 ```@setup colors
 using Plots; gr()
-Plots.reset_defaults()
+Plots.Commons.reset_defaults()
 ```
 
 # Colorschemes

diff --git a/docs/src/contributing.md b/docs/src/contributing.md
@@ -1,6 +1,6 @@
 ```@setup contributing
 using Plots; gr()
-Plots.reset_defaults()
+Plots.Commons.reset_defaults()
 ```
 
 This is a guide to contributing to Plots and the surrounding ecosystem. Plots is a complex and far-reaching suite of software components, and as such will be most effective when the community contributes their own expertise, knowledge, perspective, and effort. The document is roughly broken up into the following categories, and after reading this introduction you should feel comfortable skipping to the section(s) that interest you the most:

diff --git a/docs/src/democards/bulmagridtheme.css b/docs/src/democards/bulmagridtheme.css