Add docs folder (#4963)

* add documentation folder

* use 'pre' in ci

* move make.jl

* update for Documenter v1

* handle some more errors

* add workflow dispatch triggers to ci

* add backend imports

* add PlotsBase on CI

* earlier

* RecipesPipeline too

* fix syntax

* remove from Project

* add ImageIO ImageMagick

* add StaticArrays

* OffsetArrays

* restore old project

* remove InspectDR

* RecipesBase

* use this repo

* resolve in one go

.github/workflows/CompatHelper.yml

@@ -1,6 +1,7 @@
 name: CompatHelper
 
 on:
+  workflow_dispatch:
   schedule:
     - cron: '00 00 * * *'
 

.github/workflows/benchmark.yml

@@ -1,6 +1,7 @@
 name: benchmarks
 
 on:
+  workflow_dispatch:
   pull_request:
 
 concurrency: 

.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 name: ci
 
 on:
+  workflow_dispatch:
   pull_request:
   push:
     branches: [master, v2]
@@ -37,10 +38,7 @@ jobs:
         include:
           - os: ubuntu-latest
             experimental: true
-            version: '~1.11.0-0'  # upcoming julia version (`alpha`, `beta` or `rc`)
-          - os: ubuntu-latest
-            experimental: true
-            version: 'nightly'
+            version: 'pre'  # upcoming julia version (`alpha`, `beta` or `rc`)
 
     steps:
       - uses: actions/checkout@v4

.github/workflows/docs.yml

@@ -3,16 +3,14 @@ name: docs
 on:
  workflow_dispatch:
  push:
-  branches: [master]
+  branches: [v2]
   tags: '*'
 
 jobs:
   Build_docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          repository: JuliaPlots/PlotDocs.jl
       - uses: julia-actions/setup-julia@latest
       - name: Cache artifacts
         uses: actions/cache@v4

.github/workflows/format_check.yml

@@ -1,6 +1,7 @@
 name: format
 
 on:
+  workflow_dispatch:
   pull_request:
   push:
     branches: [master, v2]

.github/workflows/format_pr.yml

@@ -1,6 +1,7 @@
 name: format
 
 on:
+  workflow_dispatch:
   schedule:
     - cron: '0 0 1 * *'
 

.github/workflows/invalidations.yml

@@ -1,8 +1,9 @@
 name: invalidations
 on:
+  workflow_dispatch:
   pull_request:
   push:
-    branches: [master]
+    branches: [v2]
 
 concurrency: 
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}

.gitignore

@@ -14,3 +14,8 @@ test/tmpplotsave.hdf5
 /benchmark/*.json
 .vscode/
 .CondaPkg/
+
+# docs
+**/generated/
+docs/build/
+docs/work/

PlotsBase/src/plot.jl

@@ -42,15 +42,15 @@ function Base.show(io::IO, plt::Plot)
     end
     do_show = true
     for (i, ekwargs) ∈ enumerate(sp_ekwargs)
-        for (key, value) ∈ ekwargs
+        for (key, value) ∈ pairs(ekwargs)
             do_show && println(io, "  SubplotPlot{$i}:")
             println(io, " "^4, key, ": ", value)
             do_show = false
         end
         do_show = true
     end
     for (i, ekwargs) ∈ enumerate(s_ekwargs)
-        for (key, value) ∈ ekwargs
+        for (key, value) ∈ pairs(ekwargs)
             do_show && println(io, "  Series{$i}:")
             println(io, " "^4, key, ": ", value)
             do_show = false

docs/Project.toml

@@ -0,0 +1,43 @@
+[deps]
+AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+FreeType = "b38be410-82b0-50bf-ab77-7b57e271db43"
+Gaston = "4b11ee91-296f-5714-9832-002c20994614"
+GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
+Glob = "c27321d9-0574-5035-807b-f59d2c89b15c"
+GraphRecipes = "bd48cda9-67a9-57be-86fa-5b3c104eda73"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
+ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
+Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
+OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
+OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+PGFPlotsX = "8314cec4-20b6-5062-9cdb-752b83310925"
+PlotThemes = "ccf2f8ad-2431-5c83-bf29-c5338b663b6a"
+PlotlyBase = "a03496cd-edff-5a9b-9e67-9cda94a718b5"
+PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
+PlotlyKaleido = "f2990250-8cf9-495f-b13a-cce12b45703c"
+ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
+PythonPlot = "274fc56d-3b97-40fa-a1cd-1b4a50311bf9"
+RDatasets = "ce6b1742-4840-55fa-b093-852dadbb1d8b"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
+RecipesPipeline = "01d81517-befc-4cb6-b9ec-a95719d0359c"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
+UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
+Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"

docs/ci_build.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -e
+
+key_unset=false
+if [ -z "$DOCUMENTER_KEY" ]; then
+  echo '`DOCUMENTER_KEY` is missing'
+  key_unset=true
+fi
+
+tok_unset=false
+if [ -z "$GITHUB_TOKEN" ]; then
+  echo '`GITHUB_TOKEN` is missing'
+  tok_unset=true
+fi
+
+if $key_unset && $tok_unset; then
+  echo 'either `GITHUB_TOKEN` or `DOCUMENTER_KEY` must be set for `Documenter` !'
+  exit 1
+fi
+
+echo '== install system dependencies =='
+sudo apt -y update
+sudo apt -y install \
+  texlive-{latex-{base,extra},binaries,pictures,luatex} \
+  ttf-mscorefonts-installer \
+  poppler-utils \
+  ghostscript-x \
+  qtbase5-dev \
+  pdf2svg \
+  gnuplot \
+  g++
+
+echo '== install fonts =='
+mkdir -p ~/.fonts
+repo="https://github.com/cormullion/juliamono"
+ver="$(git -c 'versionsort.suffix=-' ls-remote --tags --sort='v:refname' "$repo.git" | tail -n 1 | awk '{ print $2 }' | sed 's,refs/tags/,,')"
+url="$repo/releases/download/$ver/JuliaMono-ttf.tar.gz"
+echo "downloading & extract url=$url"
+wget -q "$url" -O - | tar -xz -C ~/.fonts
+sudo fc-cache -vr
+fc-list | grep 'JuliaMono'
+
+echo "== install julia dependencies =="
+if true; then
+  export JULIA_DEBUG='Documenter,Literate,DemoCards'
+  export DOCUMENTER_DEBUG=true  # Democards.jl
+fi
+
+export LD_PRELOAD=$(g++ --print-file-name=libstdc++.so)
+export GKSwstype=nul  # Plots.jl/issues/3664
+export COLORTERM=truecolor  # UnicodePlots.jl
+export PLOTDOCS_ANSICOLOR=true
+export JULIA_CONDAPKG_BACKEND=MicroMamba
+
+julia='xvfb-run -a julia --color=yes --project=docs'
+
+# $julia -e 'using Pkg; Pkg.add(PackageSpec(url="https://github.com/JuliaPlots/Plots.jl", rev=split(ENV["GITHUB_REF"], "/", limit=3)[3], subdir="RecipesBase"));' #FIXME: not needed when registered
+# $julia -e 'using Pkg; Pkg.add(PackageSpec(url="https://github.com/JuliaPlots/Plots.jl", rev=split(ENV["GITHUB_REF"], "/", limit=3)[3], subdir="RecipesPipeline"));' #FIXME: not needed when registered
+# $julia -e 'using Pkg; Pkg.add(PackageSpec(url="https://github.com/JuliaPlots/Plots.jl", rev=split(ENV["GITHUB_REF"], "/", limit=3)[3], subdir="PlotsBase"));' #FIXME: not needed when registered
+$julia -e 'using Pkg; Pkg.develop([(;path="."), (;path="./RecipesBase"), (;path="./RecipesPipeline"), (;path="./PlotsBase")]);' #FIXME: not needed when registered
+$julia -e '
+  using Pkg; Pkg.add("CondaPkg")
+  using CondaPkg; CondaPkg.resolve()
+  libgcc = if Sys.islinux()
+    # see discourse.julialang.org/t/glibcxx-version-not-found/82209/8
+    # julia 1.8.3 is built with libstdc++.so.6.0.29, so we must restrict to this version (gcc 11.3.0, not gcc 12.2.0)
+    # see gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html
+    specs = Dict(
+      v"3.4.29" => ">=11.1,<12.1",
+      v"3.4.30" => ">=12.1,<13.1",
+      v"3.4.31" => ">=13.1,<14.1",
+      # ... keep this up-to-date with gcc 14
+    )[Base.BinaryPlatforms.detect_libstdcxx_version()]
+    ("libgcc-ng$specs", "libstdcxx-ng$specs")
+  else
+    ()
+  end
+  CondaPkg.PkgREPL.add([libgcc..., "matplotlib"])
+  CondaPkg.status()
+'
+
+echo "== build documentation for $GITHUB_REPOSITORY@$GITHUB_REF, triggered by $GITHUB_ACTOR on $GITHUB_EVENT_NAME =="
+if [ "$GITHUB_REPOSITORY" == 'JuliaPlots/PlotDocs.jl' ]; then
+  $julia -e 'using Pkg; Pkg.add(PackageSpec(name="Plots", rev="master"))'
+  $julia docs/make.jl
+elif [ "$GITHUB_REPOSITORY" == 'JuliaPlots/Plots.jl' ]; then
+  $julia -e 'using Pkg; Pkg.add(PackageSpec(name="Plots", rev=split(ENV["GITHUB_REF"], "/", limit=3)[3])); Pkg.instantiate()'
+  $julia docs/make.jl
+else
+  echo "something is wrong with $GITHUB_REPOSITORY"
+  exit 1
+fi

docs/gallery/gaston/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "bulmagrid",
+    "properties":{
+        "notebook": "false"
+    }
+}

docs/gallery/gaston/index.md

@@ -0,0 +1,12 @@
+# Gaston
+
+To switch to the `Gaston` backend, you can use:
+
+```julia
+using Plots
+gaston()
+```
+
+The demos are generated from `Plots._examples`. Empty demos are features that this backend does not support.
+
+{{{democards}}}

docs/gallery/gr/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "bulmagrid",
+    "properties":{
+        "notebook": "false"
+    }
+}

docs/gallery/gr/index.md

@@ -0,0 +1,12 @@
+# GR
+
+`GR` is the default backend for `Plots`. To explicitly specify the `GR` backend, you can use:
+
+```julia
+using Plots
+gr()
+```
+
+The demos are generated from `Plots._examples`. Empty demos are features that this backend does not support.
+
+{{{democards}}}

docs/gallery/inspectdr/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "bulmagrid",
+    "properties":{
+        "notebook": "false"
+    }
+}

docs/gallery/inspectdr/index.md

@@ -0,0 +1,15 @@
+# InspectDR
+
+!!! warn
+    `InspectDR` currently does not precompile on julia 1.10+.
+
+To switch to the `InspectDR` backend, you can use:
+
+```julia
+using Plots
+# inspectdr()
+```
+
+The demos are generated from `Plots._examples`. Empty demos are features that this backend does not support.
+
+{{{democards}}}

docs/gallery/pgfplotsx/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "bulmagrid",
+    "properties":{
+        "notebook": "false"
+    }
+}

docs/gallery/pgfplotsx/index.md

@@ -0,0 +1,12 @@
+# PGFPlotsX
+
+To switch to the `PGFPlotsX` backend, you can use:
+
+```julia
+using Plots
+pgfplotsx()
+```
+
+The demos are generated from `Plots._examples`. Empty demos are features that this backend does not support.
+
+{{{democards}}}

docs/gallery/plotlyjs/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "bulmagrid",
+    "properties":{
+        "notebook": "false"
+    }
+}

docs/gallery/plotlyjs/index.md

@@ -0,0 +1,12 @@
+# PlotlyJS
+
+To switch to the `PlotlyJS` backend, you can use:
+
+```julia
+using Plots
+plotlyjs()
+```
+
+The demos are generated from `Plots._examples`. Empty demos are features that this backend does not support.
+
+{{{democards}}}

docs/gallery/pythonplot/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "bulmagrid",
+    "properties":{
+        "notebook": "false"
+    }
+}

docs/gallery/pythonplot/index.md

@@ -0,0 +1,12 @@
+# PythonPlot
+
+To switch to the `PythonPlot` backend, you can use:
+
+```julia
+using Plots
+pythonplot()
+```
+
+The demos are generated from `Plots._examples`. Empty demos are features that this backend does not support.
+
+{{{democards}}}

docs/gallery/unicodeplots/config.json

@@ -0,0 +1,6 @@
+{
+    "theme": "bulmagrid",
+    "properties":{
+        "notebook": "false"
+    }
+}

docs/gallery/unicodeplots/index.md

@@ -0,0 +1,12 @@
+# UnicodePlots
+
+To switch to the `UnicodePlots` backend, you can use:
+
+```julia
+using Plots
+unicodeplots()
+```
+
+The demos are generated from `Plots._examples`. Empty demos are features that this backend does not support.
+
+{{{democards}}}