move docs build scripts to master (#5140)

Author: t-bltg

.github/workflows/docs.yml

@@ -7,29 +7,29 @@ on:
     tags: '*'
   release:
     types: [published]
+  pull_request:
+
+concurrency: 
+  group: ${{ github.workflow }}-${{ github.head_ref && github.ref || github.run_id }}
+  cancel-in-progress: true
 
 jobs:
-  Build_docs:
+  build:
+    if: ${{ github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'documentation') }}
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
     runs-on: ubuntu-latest
+    env:
+      PYTHON: ""
+      DOCUMENTER_KEY: ${{secrets.DOCUMENTER_KEY}}
+      GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
     steps:
       - uses: actions/checkout@v4
-        with:
-          repository: JuliaPlots/PlotDocs.jl
       - uses: julia-actions/setup-julia@latest
-      - name: Cache artifacts
-        uses: actions/cache@v4
-        env:
-          cache-name: cache-artifacts
-        with:
-          path: ~/.julia/artifacts 
-          key: ${{runner.os}}-test-${{env.cache-name}}-${{hashFiles('**/Project.toml')}}
-          restore-keys: |
-            ${{runner.os}}-test-${{env.cache-name}}-
-            ${{runner.os}}-test-
-            ${{runner.os}}-
-      - name: Build documentation
-        env:
-          PYTHON: ""
-          DOCUMENTER_KEY: ${{secrets.DOCUMENTER_KEY}}
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
-        run: bash docs/ci_build.sh
+      - uses: julia-actions/cache@v2
+      - run: bash -c '. ci/build-docs.sh; install_ubuntu_deps'
+      - run: bash -c '. ci/build-docs.sh; install_and_precompile_julia_deps'
+      - run: bash -c '. ci/build-docs.sh; build_documenter_docs'

.gitignore

@@ -1,16 +1,24 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+
 .DS_Store
 examples/.ipynb_checkpoints/*
 examples/meetup/.ipynb_checkpoints/*
+
 deps/plotly-*
 deps/build.log
 deps/deps.jl
 Manifest.toml
+
 dev/
 test/tmpplotsave.hdf5
 /.benchmarkci
 /benchmark/*.json
 .vscode/
-.CondaPkg/
+.CondaPkg/
+
+# docs
+**/generated/
+docs/build*/
+docs/work*/

ci/build-docs.sh

@@ -0,0 +1,74 @@
+#!/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
+
+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 MPLBACKEND=agg
+export COLORTERM=truecolor  # UnicodePlots.jl
+export PLOTDOCS_ANSICOLOR=true
+export JULIA_CONDAPKG_BACKEND=MicroMamba
+
+julia_project() {
+  xvfb-run -a julia --color=yes --project=docs "$@"
+}
+
+install_ubuntu_deps() {
+  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'
+}
+
+install_and_precompile_julia_deps() {
+  echo "== install julia dependencies =="
+  JULIA_PKG_PRECOMPILE_AUTO=0 julia_project ci/matplotlib.jl
+  echo '== precompile docs dependencies =='
+  julia_project docs/make.jl none
+}
+
+build_documenter_docs() {
+  echo "== build documentation for $GITHUB_REPOSITORY@$GITHUB_REF, triggered by $GITHUB_ACTOR on $GITHUB_EVENT_NAME =="
+  # export PLOTDOCS_PACKAGES='UnicodePlots'
+  # export PLOTDOCS_PUSH_PREVIEW=true
+  # export PLOTDOCS_EXAMPLES=1
+  julia_project docs/make.jl
+}

ci/matplotlib.jl

@@ -0,0 +1,41 @@
+using Pkg
+Pkg.add("CondaPkg")
+
+using CondaPkg
+CondaPkg.resolve()
+
+# table adapted from `4. Symbol versioning on the libstdc++.so binary` in
+# gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html
+# see also github.com/gcc-mirror/gcc/blob/master/libstdc%2B%2B-v3/config/abi/pre/gnu.ver
+_compatible_libstdcxx_ng_versions = [
+    (v"3.4.34", (">=15.1", "<16.1")),  # NOTE: hypothetical upper bound
+    (v"3.4.33", (">=14.1", "<15.1")),
+    (v"3.4.32", (">=13.2", "<14.1")),
+    (v"3.4.31", (">=13.1", "<13.2")),
+    (v"3.4.30", (">=12.1", "<13.1")),
+    (v"3.4.29", (">=11.1", "<12.1")),
+    (v"3.4.28", (">=9.3", "<11.1")),
+    (v"3.4.27", (">=9.2", "<9.3")),
+    (v"3.4.26", (">=9.1", "<9.2")),
+    (v"3.4.25", (">=8.1", "<9.1")),
+    (v"3.4.24", (">=7.2", "<8.1")),
+    (v"3.4.23", (">=7.1", "<7.2")),
+    (v"3.4.22", (">=6.1", "<7.1")),
+    (v"3.4.21", (">=5.1", "<6.1")),
+    (v"3.4.20", (">=4.9", "<5.1")),
+    (v"3.4.19", (">=4.8.3", "<4.9")),
+]
+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)
+    versions = Dict(_compatible_libstdcxx_ng_versions)
+    lo, hi = extrema(keys(versions))
+    _, ub = versions[Base.BinaryPlatforms.detect_libstdcxx_version(Int(hi.patch))]
+    specs = ">=$(VersionNumber(lo.major, lo.minor)),$ub"
+    ("libgcc-ng$specs", "libstdcxx-ng$specs")
+else
+    ()
+end
+
+CondaPkg.PkgREPL.add([libgcc..., "matplotlib>=3.4"])  # "openssl>=3.4"
+CondaPkg.status()

docs/Project.toml

@@ -0,0 +1,77 @@
+[deps]
+AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
+CondaPkg = "992eb4ea-22a4-4c89-a5bb-47a3300528ab"
+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"
+InspectDR = "d0351b0e-4b05-5898-87b3-e2a8edfddd1d"
+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"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+PlotlyBase = "a03496cd-edff-5a9b-9e67-9cda94a718b5"
+PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
+PlotlyKaleido = "f2990250-8cf9-495f-b13a-cce12b45703c"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+PlotThemes = "ccf2f8ad-2431-5c83-bf29-c5338b663b6a"
+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"
+StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
+TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
+UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
+Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+
+[compat]
+DataFrames = "1"
+Dates =  "1"
+Documenter = "1"
+FileIO = "1"
+FreeType = "4"
+Gaston = "1"
+Glob = "1"
+LaTeXStrings = "1"
+Literate = "2"
+LinearAlgebra = "1"
+OffsetArrays = "1"
+OrderedCollections = "1"
+Pkg = "1"
+Plots = "1"
+PlotThemes = "3"
+PGFPlotsX = "1"
+PythonPlot = "1"
+SparseArrays = "1"
+StableRNGs = "1"
+StaticArrays = "1"
+TestImages = "1"
+UnicodePlots = "3"
+Unitful = "1"
+
+[sources]
+Plots = {path = ".."}
+RecipesBase = {path = "../RecipesBase"}
+RecipesPipeline = {path = "../RecipesPipeline"}

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"
+    }
+}