Call for Plots examples

Specific Domains Visualization
,
1

I’m not an experienced Plots user; every time when I use Plots I try to find an example that looks useful and try to modify it.

With the help of @BeastyBlacksmith we’ve finally set up the demo gallery using DemoCards.jl, the latest version can be found in User Gallery · Plots. If you have interesting examples, it would be super helpful to add them there.

Building the Plots documentation is time-consuming (>30mins) so here’s a brief guide on how you can build the demos within 3mins:

  1. fork the PlotDocs repo
  2. create a demo file in any sub-folder of docs/user_gallery
  3. preview it using DemoCards.preview_demos
  4. open a PR to PlotDocs when you’re satisfied.

The principle is quite simple: each Julia script corresponds to a demo.

Example

Assume that we’re adding one demo “gr_line_plot.jl” to “docs/user_gallery/misc” folder:

# ---
# title: Line plot
# author: Johnny Chen
# cover: assets/gr_line_plot.png
# date: 2022-03-21
# ---

using Plots

# This example shows how to use Plots to draw a line
plot(1:10)

## generating cover image on the fly
mkpath("assets") #src
png("assets/gr_line_plot.png") #src

The DemoCards.jl YAML frontmatter defines some of the basic information of this demo. Note that the cover image "assets/gr_line_plot.png" is generated at the end of the script.

There are some Literate.jl markups here:

  • leading # indicates a markdown line
  • leading ## indicates a Julia comment line
  • trailing #src indicates that this won’t be shown in the generated demo

Here’s the result if you build this specific example:

julia> using DemoCards

julia> @time preview_demos("docs/user_gallery/misc/gr_line_plot.jl")
[ Info: SetupDemoCardsDirectory: setting up "user_gallery" directory.
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Redirect page URL: redirect docs-edit-link for demos in "user_gallery" directory.
[ Info: Clean up DemoCards build dir: "user_gallery"
  0.214942 seconds (71.78 k allocations: 10.674 MiB, 1.35% compilation time)
"/tmp/jl_hAAUbH/build/index.html"

then open the path in your favorite browser:

1647864918(1)
1647864918(1)1796×1086 86.5 KB

image
image1774×1374 94.5 KB

Note that previewing the demo will be super-fast 0.2s in this case since it doesn’t build the entire documentation.

You can also preview all demos in specific folder. For instance:

julia> @time preview_demos("docs/user_gallery/misc")
[ Info: SetupDemoCardsDirectory: setting up "user_gallery" directory.
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Redirect page URL: redirect docs-edit-link for demos in "user_gallery" directory.
[ Info: Clean up DemoCards build dir: "user_gallery"
  7.655850 seconds (9.66 M allocations: 422.247 MiB, 0.80% gc time, 0.65% compilation time)
"/tmp/jl_hAAUbH/build/index.html"

image
image1741×1070 151 KB

This is a bit slower since you need to build more demos.

When you’re satisfied with your demo, open a PR to the PlotDocs. For this trivial example, you can find the PR here

6 Likes