fix docs on v2 (#4999)

* fix docs on v2 * fix test * unexport center, too generic * update
JuliaPlots · Oct 13, 2024 · c1cfa30 · c1cfa30
1 parent fa63411
commit c1cfa30
Show file tree

Hide file tree

Showing 21 changed files with 80 additions and 89 deletions.
diff --git a/PlotsBase/src/PlotsBase.jl b/PlotsBase/src/PlotsBase.jl
@@ -108,11 +108,6 @@ export
     test_examples,
     coords,
 
-    translate,
-    translate!,
-    rotate,
-    rotate!,
-    center,
     plotattr,
     scalefontsizes,
     resetfontsizes

diff --git a/PlotsBase/test/test_components.jl b/PlotsBase/test/test_components.jl
@@ -38,7 +38,7 @@
         @test PlotsBase.translate(square, 0, 1).x == squareUp.x
         @test PlotsBase.translate(square, 0, 1).y == squareUp.y
 
-        @test PlotsBase.center(translate!(square, 1)) == (1.5, 1.5)
+        @test PlotsBase.center(PlotsBase.translate!(square, 1)) == (1.5, 1.5)
     end
 
     @testset "Rotate" begin

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,21 +640,21 @@ 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",
             ],
         ],
         "Manual" => [
-            "Input Data" => "input_data.md",
+            # "Input Data" => "input_data.md",  # TODO: uncomment once StatsPlots is ready
             "Output" => "output.md",
             "Attributes" => "attributes.md",
             "Series Attributes" => "generated/attributes_series.md",
             "Plot Attributes" => "generated/attributes_plot.md",
             "Subplot Attributes" => "generated/attributes_subplot.md",
             "Axis Attributes" => "generated/attributes_axis.md",
-            "Layouts" => "layouts.md",
+            # "Layouts" => "layouts.md",  # TODO: uncomment once StatsPlots is ready
             "Recipes" => [
                 "Overview" => "recipes.md",
                 "RecipesBase" => [
@@ -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