update docs for v2 (#5012)

JuliaPlots · Nov 2, 2024 · 43e7f65 · 43e7f65
1 parent 8119dac
commit 43e7f65
Show file tree

Hide file tree

Showing 10 changed files with 107 additions and 96 deletions.
diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
@@ -13,5 +13,5 @@ jobs:
     - uses: actions/checkout@v4
     - uses: codespell-project/actions-codespell@v2
       with:
-        ignore_words_list: nd,nax,linez,ist
+        ignore_words_list: nd,nax,namin,namax,linez,ist
         only_warn: 0
diff --git a/PlotsBase/src/init.jl b/PlotsBase/src/init.jl
@@ -22,7 +22,7 @@ function _plots_theme_defaults()
 end
 
 function _plots_plotly_defaults()
-    if bool_env("PLOTS_HOST_DEPENDENCY_LOCAL", "false")
+    if Base.get_bool_env("PLOTS_HOST_DEPENDENCY_LOCAL", false)
         _plotly_local_file_path[] =
             fn = joinpath(@get_scratch!("plotly"), _plotly_min_js_filename)
         isfile(fn) ||

diff --git a/PlotsBase/src/utils.jl b/PlotsBase/src/utils.jl
@@ -1,6 +1,4 @@
 
-bool_env(x, default::String = "0")::Bool = tryparse(Bool, get(ENV, x, default))
-
 treats_y_as_x(seriestype) =
     seriestype in (:vline, :vspan, :histogram, :barhist, :stephist, :scatterhist)
 

diff --git a/PlotsBase/test/runtests.jl b/PlotsBase/test/runtests.jl
@@ -46,9 +46,9 @@ using FileIO
 using Dates
 using Test
 
-is_auto() = PlotsBase.bool_env("VISUAL_REGRESSION_TESTS_AUTO")
-is_pkgeval() = PlotsBase.bool_env("JULIA_PKGEVAL")
-is_ci() = PlotsBase.bool_env("CI")
+is_auto() = Base.get_bool_env("VISUAL_REGRESSION_TESTS_AUTO", false)
+is_pkgeval() = Base.get_bool_env("JULIA_PKGEVAL", false)
+is_ci() = Base.get_bool_env("CI", false)
 
 is_ci() || @eval using Gtk  # see JuliaPlots/VisualRegressionTests.jl/issues/30
 

diff --git a/PlotsBase/test/test_misc.jl b/PlotsBase/test/test_misc.jl
@@ -63,13 +63,6 @@ end
     end
 end
 
-@testset "bool_env" begin
-    @test PlotsBase.bool_env("FOO", "true")
-    @test PlotsBase.bool_env("FOO", "1")
-    @test !PlotsBase.bool_env("FOO", "false")
-    @test !PlotsBase.bool_env("FOO", "0")
-end
-
 @testset "Themes" begin
     @test showtheme(:dark) isa PlotsBase.Plot
 end

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -24,10 +24,13 @@ OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 PGFPlotsX = "8314cec4-20b6-5062-9cdb-752b83310925"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 PlotThemes = "ccf2f8ad-2431-5c83-bf29-c5338b663b6a"
 PlotlyBase = "a03496cd-edff-5a9b-9e67-9cda94a718b5"
 PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
 PlotlyKaleido = "f2990250-8cf9-495f-b13a-cce12b45703c"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+PlotsBase = "c52230a3-c5da-43a3-9e85-260fcdfdc737"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 PythonPlot = "274fc56d-3b97-40fa-a1cd-1b4a50311bf9"
 RDatasets = "ce6b1742-4840-55fa-b093-852dadbb1d8b"
@@ -36,9 +39,9 @@ RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 RecipesPipeline = "01d81517-befc-4cb6-b9ec-a95719d0359c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
-StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,3 +1,14 @@
+using Pkg
+Base.get_bool_env("PLOTDOCS_DEV", false) && Pkg.develop([
+    (; path="../RecipesBase"),
+    (; path="../RecipesPipeline"),
+    (; path="../PlotsBase"),
+    (; path=".."),
+    (; path="../GraphRecipes"),
+    (; path="../StatsPlots"),
+])
+# oneliner debug PLOTDOCS_DEV=1 PLOTDOCS_PACKAGES='GR' PLOTDOCS_EXAMPLES=1 julia --project -e 'include("make.jl")'
+
 using DataFrames, OrderedCollections, Dates
 using MacroTools: rmlines
 using PlotThemes, Plots, RecipesBase, RecipesPipeline
@@ -13,6 +24,7 @@ import StatsPlots
 const SRC_DIR = joinpath(@__DIR__, "src")
 const WORK_DIR = joinpath(@__DIR__, "work")
 const GEN_DIR = joinpath(WORK_DIR, "generated")
+const BRANCH = ("master", "v2")[2]  # transition to v2
 
 const ATTRIBUTE_SEARCH = Dict{String,Any}()  # search terms
 
@@ -57,7 +69,7 @@ end
 # ----------------------------------------------------------------------
 
 edit_url(args...) =
-    "https://github.com/JuliaPlots/Plots.jl/blob/master/docs/" * if length(args) == 0
+    "https://github.com/JuliaPlots/Plots.jl/blob/$BRANCH/docs/" * if length(args) == 0
         "make.jl"
     else
         joinpath("src", args...)
@@ -626,81 +638,87 @@ function main()
     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")
+        let (path, cb, assets) = makedemos(joinpath("gallery", string(be)); src="$work/gallery", edit_branch=BRANCH)
             push!(gallery, string(pkg) => joinpath("gallery", path))
             push!(gallery_callbacks, cb)
             push!(gallery_assets, assets)
         end
     end
-    user_gallery, cb, assets = makedemos(joinpath("user_gallery"); src = work)
+    user_gallery, cb, assets = makedemos(joinpath("user_gallery"); src=work, edit_branch=BRANCH)
     push!(gallery_callbacks, cb)
     push!(gallery_assets, assets)
     unique!(gallery_assets)
-
-    pages = [
-        "Home" => "index.md",
-        "Getting Started" => [
-            "Installation" => "install.md",
-            "Basics" => "basics.md",
-            "Tutorial" => "tutorial.md",
-            "Series Types" => [
-                "Contour Plots" => "series_types/contour.md",
-                "Histograms" => "series_types/histogram.md",
-            ],
-        ],
-        "Manual" => [
-            "Input Data" => "input_data.md",
-            "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",
-            "Recipes" => [
-                "Overview" => "recipes.md",
-                "RecipesBase" => [
-                    "Home" => "RecipesBase/index.md",
-                    "Recipes Syntax" => "RecipesBase/syntax.md",
-                    "Recipes Types" => "RecipesBase/types.md",
-                    "Internals" => "RecipesBase/internals.md",
-                    "Public API" => "RecipesBase/api.md",
-                ],
-                "RecipesPipeline" => [
-                    "Home" => "RecipesPipeline/index.md",
-                    "Public API" => "RecipesPipeline/api.md",
+    @show user_gallery gallery_assets
+
+
+    pages = if (debug = length(packages) ≤ 1)  # debug
+        ["Home" => "index.md", "Gallery" => gallery, "User Gallery" => user_gallery]
+    else  # release
+        [
+            "Home" => "index.md",
+            "Getting Started" => [
+                "Installation" => "install.md",
+                "Basics" => "basics.md",
+                "Tutorial" => "tutorial.md",
+                "Series Types" => [
+                    "Contour Plots" => "series_types/contour.md",
+                    "Histograms" => "series_types/histogram.md",
                 ],
             ],
-            "Colors" => "colors.md",
-            "ColorSchemes" => "generated/colorschemes.md",
-            "Animations" => "animations.md",
-            "Themes" => "generated/plotthemes.md",
-            "Backends" => "backends.md",
-            "Supported Attributes" => "generated/supported.md",
-        ],
-        "Learning" => "learning.md",
-        "Contributing" => "contributing.md",
-        "Ecosystem" => [
-            "StatsPlots" => "generated/statsplots.md",
-            "GraphRecipes" => [
-                "Introduction" => "GraphRecipes/introduction.md",
-                "Examples" => "GraphRecipes/examples.md",
-                "Attributes" => "generated/graph_attributes.md",
+            "Manual" => [
+                "Input Data" => "input_data.md",
+                "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",
+                "Recipes" => [
+                    "Overview" => "recipes.md",
+                    "RecipesBase" => [
+                        "Home" => "RecipesBase/index.md",
+                        "Recipes Syntax" => "RecipesBase/syntax.md",
+                        "Recipes Types" => "RecipesBase/types.md",
+                        "Internals" => "RecipesBase/internals.md",
+                        "Public API" => "RecipesBase/api.md",
+                    ],
+                    "RecipesPipeline" => [
+                        "Home" => "RecipesPipeline/index.md",
+                        "Public API" => "RecipesPipeline/api.md",
+                    ],
+                ],
+                "Colors" => "colors.md",
+                "ColorSchemes" => "generated/colorschemes.md",
+                "Animations" => "animations.md",
+                "Themes" => "generated/plotthemes.md",
+                "Backends" => "backends.md",
+                "Supported Attributes" => "generated/supported.md",
             ],
-            "UnitfulExt" => [
-                "Introduction" => "UnitfulExt/unitfulext.md",
-                "Examples" => [
-                    "Simple" => "generated/unitfulext_examples.md",
-                    "Plots" => "generated/unitfulext_plots.md",
-                ]
+            "Learning" => "learning.md",
+            "Contributing" => "contributing.md",
+            "Ecosystem" => [
+                "StatsPlots" => "generated/statsplots.md",
+                "GraphRecipes" => [
+                    "Introduction" => "GraphRecipes/introduction.md",
+                    "Examples" => "GraphRecipes/examples.md",
+                    "Attributes" => "generated/graph_attributes.md",
+                ],
+                "UnitfulExt" => [
+                    "Introduction" => "UnitfulExt/unitfulext.md",
+                    "Examples" => [
+                        "Simple" => "generated/unitfulext_examples.md",
+                        "Plots" => "generated/unitfulext_plots.md",
+                    ]
+                ],
+                "Overview" => "ecosystem.md",
             ],
-            "Overview" => "ecosystem.md",
-        ],
-        "Advanced Topics" => ["Plot objects" => "plot_objects.md","Plotting pipeline" => "pipeline.md"],
-        "Gallery" => gallery,
-        "User Gallery" => user_gallery,
-        "API" => "api.md",
-    ]
+            "Advanced Topics" => ["Plot objects" => "plot_objects.md","Plotting pipeline" => "pipeline.md"],
+            "Gallery" => gallery,
+            "User Gallery" => user_gallery,
+            "API" => "api.md",
+        ]
+    end
 
     # those will be built pages - to skip some pages, comment them above
     selected_pages = []
@@ -713,7 +731,7 @@ function main()
 
     collect_pages!(pages)
     unique!(selected_pages)
-    # @show selected_pages length(gallery) length(user_gallery)
+    @show debug selected_pages length(gallery) pages
 
     n = 0
     for (root, dirs, files) ∈ walkdir(SRC_DIR)
@@ -742,37 +760,40 @@ function main()
         nb && Literate.notebook(ipath, notebooks; execute)
     end
 
-    ansicolor = get(ENV, "PLOTDOCS_ANSICOLOR", "true") == "true"
-    @info "makedocs" ansicolor
+    ansicolor = Base.get_bool_env("PLOTDOCS_ANSICOLOR", true)
+    @info "makedocs ansicolor=$ansicolor" 
     failed = false
     try
         @time makedocs(;
+            root = @__DIR__,
             source = work,
             format = Documenter.HTML(;
                 size_threshold = nothing,
-                prettyurls = get(ENV, "CI", nothing) == "true",
+                prettyurls = Base.get_bool_env("CI", false),
                 assets = ["assets/favicon.ico", gallery_assets...],
                 collapselevel = 2,
                 ansicolor,
             ),
+            # modules = [RecipesBase, RecipesPipeline],
+            # pagesonly = true,  # fails DemoCards !
             sitename = "Plots",
             authors = "Thomas Breloff",
-            warnonly = true,
-            pagesonly = true,
+            warnonly = debug,
             pages,
         )
     catch e
         failed = true
         e isa InterruptException || rethrow()
     end
 
+    @info "gallery_callbacks"
     foreach(gallery_callbacks) do cb
         cb()  # URL redirection for DemoCards-generated gallery
     end
 
     failed && return  # don't deploy and post-process on failure
 
-    # postprocess gallery html files to remove `rng` in user displayed code
+    @info "post-process 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 pkg ∈ packages
@@ -806,14 +827,15 @@ function main()
         end
     end
 
-    # postprocess temporary work dir
+    @info "post-process temporary work dir"
     src = basename(SRC_DIR)
     for file ∈ glob("*/index.html", joinpath(@__DIR__, "build"))
         lines = readlines(file; keep=true)
-        any((occursin("blob/master/docs", line) for line ∈ lines)) || continue
+        any(line -> occursin("blob/$BRANCH/docs", line), lines) || continue
+        @info "fixing $file"
         open(file, "w") do io
             for line ∈ lines
-                write(io, replace(line, "blob/master/docs/$work" => "blob/master/docs/$src"))
+                write(io, replace(line, "blob/$BRANCH/docs/$work" => "blob/$BRANCH/docs/$src"))
             end
         end
     end
@@ -828,6 +850,7 @@ function main()
             repo,
         )
     end
+    @info "done !"
 end
 
 main()
diff --git a/docs/src/UnitfulExt/unitfulext.md b/docs/src/UnitfulExt/unitfulext.md
@@ -20,6 +20,6 @@ Pictures speak louder than words, so we wrote some examples (accessible through
 
 ---
 
-### Ommissions, bugs, and contributing
+### Omissions, bugs, and contributing
 
 Please do not hesitate to raise an [issue](https://github.com/JuliaPlots/Plots.jl/issues) or submit a [PR](https://github.com/JuliaPlots/Plots.jl/pulls) if you would like a new recipe to be added.
diff --git a/docs/src/UnitfulExt/unitfulext_examples.jl b/docs/src/UnitfulExt/unitfulext_examples.jl
@@ -2,9 +2,6 @@
 # # [Simple Examples](@id 1_Examples)
 #---------------------------------------------------------
 
-#md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/1_Examples.ipynb)
-#md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/1_Examples.ipynb)
-
 #md # !!! note
 #md #     These examples are available as Jupyter notebooks.
 #md #     You can execute them online with [binder](https://mybinder.org/) or just view them with [nbviewer](https://nbviewer.jupyter.org/) by clicking on the badges above!

diff --git a/docs/src/UnitfulExt/unitfulext_plots.jl b/docs/src/UnitfulExt/unitfulext_plots.jl
@@ -2,9 +2,6 @@
 # # [Plots.jl examples](@id 2_Plots)
 #---------------------------------------------------------
 
-#md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/examples/2_Plots.ipynb)
-#md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/examples/2_Plots.ipynb)
-
 #md # !!! note
 #md #     These examples are available as Jupyter notebooks.
 #md #     You can execute them online with [binder](https://mybinder.org/) or just view them with [nbviewer](https://nbviewer.jupyter.org/) by clicking on the badges above!