integrate RecipesBase and RecipesPipeline into Plots

.github/workflows/ci.yml

@@ -20,7 +20,6 @@ jobs:
       GKS_ENCODING: "utf8"
       GKSwstype: "nul"
       PYTHON: "Conda"  # for `PyPlot`
-
     name: Julia ${{ matrix.version }} - ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     continue-on-error: ${{ matrix.version == 'nightly' }}
@@ -31,33 +30,34 @@ jobs:
           - '1.6' # LTS (minimal declared julia compat in `Project.toml`)
           - '1.8' # latest stable
         os: [ubuntu-latest, windows-latest, macos-latest]
-        arch:
-          - x64
+        arch: [x64]
         include:
           - os: ubuntu-latest
             prefix: xvfb-run  # julia-actions/julia-runtest/blob/master/README.md
           - os: ubuntu-latest
             prefix: xvfb-run
-            version: '1.7'
+            version: '1.7'  # only test intermediate relase on `ubuntu`
           # - os: ubuntu-latest
           #   prefix: xvfb-run
-          #  version: 'nightly'
+          #   version: 'nightly'
 
     steps:
       - uses: actions/checkout@v3
       - uses: julia-actions/setup-julia@latest
         with:
           version: ${{ matrix.version }}
       - uses: julia-actions/cache@v1
+      - uses: julia-actions/julia-buildpkg@latest
 
-      - name: Ubuntu LaTeX dependencies
-        if: startsWith(matrix.os, 'ubuntu')
+      - name: test upstream RecipesBase
+        shell: julia --project=@. --color=yes {0}
         run: |
-          sudo apt-get -y update
-          sudo apt-get -y install gnuplot poppler-utils texlive-{latex-base,latex-extra,luatex}
-          sudo fc-cache -vr
+          using Pkg; Pkg.develop(path="RecipesBase"); Pkg.test("RecipesBase")
 
-      - uses: julia-actions/julia-buildpkg@latest
+      - name: test upstream RecipesPipeline
+        shell: julia --project=@. --color=yes {0}
+        run: |
+          using Pkg; Pkg.develop(path="RecipesPipeline"); Pkg.test("RecipesPipeline")
 
       - name: PyPlot dependencies
         shell: julia --project=@. --color=yes {0}
@@ -71,15 +71,23 @@ jobs:
           Conda.add("matplotlib")
           Conda.list()
 
+      - name: Ubuntu LaTeX dependencies
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install gnuplot poppler-utils texlive-{latex-base,latex-extra,luatex}
+          sudo fc-cache -vr
+
       - uses: julia-actions/julia-runtest@latest
         with:
           prefix: ${{ matrix.prefix }}  # for `xvfb-run`
 
       - name: Run downstream tests
         if: startsWith(matrix.os, 'ubuntu')
-        run:  |
-          xvfb-run julia -e 'using Pkg; Pkg.activate(tempdir()); Pkg.develop(path=abspath(".")); Pkg.add("StatsPlots"); Pkg.test("StatsPlots")'
-          xvfb-run julia -e 'using Pkg; Pkg.activate(tempdir()); Pkg.develop(path=abspath(".")); Pkg.add("GraphRecipes"); Pkg.test("GraphRecipes")'
+        shell: xvfb-run julia --project=@. --color=yes {0}
+        run: |
+          using Pkg; Pkg.activate(tempdir()); Pkg.develop(path=abspath(".")); Pkg.add("StatsPlots"); Pkg.test("StatsPlots")
+          using Pkg; Pkg.activate(tempdir()); Pkg.develop(path=abspath(".")); Pkg.add("GraphRecipes"); Pkg.test("GraphRecipes")
 
       - uses: julia-actions/julia-processcoverage@latest
         if: startsWith(matrix.os, 'ubuntu')

RecipesBase/LICENSE.md

@@ -0,0 +1,22 @@
+The RecipesBase.jl package is licensed under the MIT "Expat" License:
+
+> Copyright (c) 2016: Thomas Breloff.
+>
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> "Software"), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+>
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

RecipesBase/Project.toml

@@ -0,0 +1,18 @@
+name = "RecipesBase"
+uuid = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
+author = ["Tom Breloff (@tbreloff)"]
+version = "1.3.0"
+
+[deps]
+SnoopPrecompile = "66db9d55-30c0-4569-8b51-7e840670fc0c"
+
+[compat]
+SnoopPrecompile = "1"
+julia = "1.6"
+
+[extras]
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Random", "Test"]

RecipesBase/README.md

@@ -0,0 +1,150 @@
+# RecipesBase
+
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaPlots.github.io/RecipesBase.jl/stable)
+[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaPlots.github.io/RecipesBase.jl/dev)
+[![Build Status](https://travis-ci.org/JuliaPlots/RecipesBase.jl.svg?branch=master)](https://travis-ci.org/JuliaPlots/RecipesBase.jl)
+[![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://julialang.zulipchat.com/#narrow/stream/236493-plots)
+[![deps](https://juliahub.com/docs/RecipesBase/deps.svg)](https://juliahub.com/ui/Packages/RecipesBase/8e2Mm?t=2)
+
+### Author: Thomas Breloff (@tbreloff)
+
+This package implements handy macros `@recipe` and `@series` which will define a custom transformation
+and attach attributes for user types.  Its design is an attempt to simplify and generalize
+the summary and display of types and data from external packages.  With no extra dependencies
+and minimal code, package authors can describe visualization routines that can be used
+as components in more complex visualizations.
+
+This functionality is primarily geared to turning user types and settings into the
+data and attributes that describe a [Plots](https://github.com/tbreloff/Plots.jl) visualization,
+though it could be used for other purposes as well.
+Plots has extensive machinery to uniquely take advantage of the simplified recipe description you define.  See the [Plots documentation on recipes](http://docs.juliaplots.org/latest/recipes/) for more information.
+
+The `@recipe` macro will process a function definition, use `-->` commands to define attributes, and
+pass the return value through for further processing (likely by Plots.jl).
+
+## Why should I care about this package?
+
+Many packages have custom types and custom data.  There is usually specialized structure, and useful
+methods of visualizing that structure and data.  This package solves the difficult problem of how to
+build generic visualizations of user-defined data types, without adding bulky dependencies on complex
+graphics packages.
+
+This package is as lightweight as possible.  It exports two macros, and defines only a few internal methods.
+It has **zero dependencies**.
+
+However, although it is lightweight, it enables a lot.  The entirety of the Plots framework becomes available
+to any package implementing a recipe.  This means that complex plots and subplots can be built with uber-flexibility
+using custom combinations of data types.  Some examples of applications:
+
+- Distributions: overlayed density plots for non-normal fitted distributions.
+- DataFrames: "Grammar of Graphics"-style inputs using symbols.
+- Deep Learning: frameworks for visualization of neural network states and tracking of internal calculations.
+- Graphs: flexible, interactive graphs with easily customizable colors, etc.
+- Symbolic frameworks: sample from complex symbolic distributions.
+
+Really there's very little that *couldn't* be mapped to a useful visualization.
+I challenge you to create the pictures that are worth a thousand words.
+
+For more information about Plots, see [the docs](http://juliaplots.github.io/), and be sure to reference
+the [supported keywords](https://docs.juliaplots.org/stable/generated/supported/#Keyword-Arguments).
+For additional examples of recipes in the wild, see [PlotRecipes](https://github.com/JuliaPlots/PlotRecipes.jl).
+Ask questions on [gitter](https://gitter.im/tbreloff/Plots.jl) or in the issues.
+
+## Hello world
+
+This will build a spiky surface:
+
+```julia
+using Plots; gr()
+struct T end
+@recipe f(::T) = rand(100,100)
+surface(T())
+```
+
+![](https://cloud.githubusercontent.com/assets/933338/15089193/7a453ec6-13cc-11e6-9ae8-959e98b615dc.png)
+
+## A real example
+
+```julia
+using RecipesBase
+
+# Our user-defined data type
+struct T end
+
+# This is all we define.  It uses a familiar signature, but strips it apart
+# in order to add a custom definition to the internal method `RecipesBase.apply_recipe`
+@recipe function plot(::T, n = 1; customcolor = :green)
+    markershape --> :auto        # if markershape is unset, make it :auto
+    markercolor :=  customcolor  # force markercolor to be customcolor
+    xrotation   --> 45           # if xrotation is unset, make it 45
+    zrotation   --> 90           # if zrotation is unset, make it 90
+    rand(10,n)                   # return the arguments (input data) for the next recipe
+end
+
+# ----------------------------
+
+# Plots will be the ultimate consumer of our recipe in this example
+using Plots
+gr()
+
+# This call will implicitly call `RecipesBase.apply_recipe` as part of the Plots
+# processing pipeline (see the Pipeline section of the Plots documentation).
+#   It will plot 5 line plots (a 5-column matrix is returned from the recipe).
+#   All will have black circles:
+#       - user override for markershape: :c == :circle
+#       - customcolor overridden to :black, and markercolor is forced to be customcolor
+#   If markershape is an unsupported keyword, the call will error.
+#   By default, a warning will be shown for an unsupported keyword.
+#   This will be suppressed for zrotation (:quiet flag).
+plot(T(), 5; customcolor = :black, shape=:c)
+```
+
+![](https://cloud.githubusercontent.com/assets/933338/15083906/02a06810-139e-11e6-98a0-dd81c3fb1ad8.png)
+
+In this example, we see a lot of the machinery in action.  We create a new type `T`, which
+we will use for dispatch, and an optional argument `n`, which will be used to determine the
+number of series to display.  User-defined keyword arguments are passed through, and the
+`-->` command can be trailed by flags:
+
+- `quiet`:   Suppress unsupported keyword warnings
+- `require`: Error if keyword is unsupported
+- `force`:   Don't allow user override for this keyword
+
+### Series
+
+For complex visualizations, it can be beneficial to create many series inside a single recipe.  The `@series` macro will make a copy of the attribute dictionary `d`, and add a new RecipeData object to the returned list.  See the [case studies](http://docs.juliaplots.org/latest/recipes/#case-studies) for more details.
+
+### Generated code
+
+For the example above, the following code is generated.  In it, you can see the managing of the scope of the keyword args, creation of a definition for `RecipesBase.apply_recipe`, setting attributes, and creating the list of `RecipeData` objects:
+
+```julia
+function RecipesBase.apply_recipe(d::Dict{Symbol,Any},::T,n=1)
+    if RecipesBase._debug_recipes[1]
+        println("apply_recipe args: ",Any[:(::T),:(n=1)])
+    end
+    begin
+        customcolor = get!(d,:customcolor,:green)
+    end
+    series_list = RecipesBase.RecipeData[]
+    func_return = begin
+            get!(d,:markershape,:auto)
+            d[:markercolor] = customcolor
+            get!(d,:xrotation,45)
+            get!(d,:zrotation,90)
+            rand(10,n)
+        end
+    if func_return != nothing
+        push!(series_list,RecipesBase.RecipeData(d,RecipesBase.wrap_tuple(func_return)))
+    end
+    begin
+        RecipesBase.is_key_supported(:customcolor) || delete!(d,:customcolor)
+    end
+    series_list
+end
+```
+
+### A humble request
+
+If you build a recipe for your package, please let me know!  I'd love to compile both a gallery and
+a listing of user-defined recipes, as well as the packages that are available for Plots visualizations.