From 661bf61fd9d65c4c6c9d8c8c08c1347e5f780a39 Mon Sep 17 00:00:00 2001
From: Aaron Kaw <aaronjkaw@gmail.com>
Date: Wed, 21 Feb 2024 23:27:02 +1100
Subject: [PATCH] Added doc on Makie package extension

---
 docs/explanations/recipes.md | 54 ++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/docs/explanations/recipes.md b/docs/explanations/recipes.md
index 17e66c6f69d..0b1d43fb663 100644
--- a/docs/explanations/recipes.md
+++ b/docs/explanations/recipes.md
@@ -341,3 +341,57 @@ GLMakie.activate!() # hide
 ```
 
 \video{stockchart_animation}
+
+## Makie Package Extension
+
+For a simple example of a package extension for Makie,
+see <https://github.com/jkrumbiegel/MakiePkgExtTest>.
+The following documentation explains the basics of the implementation
+in the linked example.
+
+Set up your [package extension](https://pkgdocs.julialang.org/v1/creating-packages/#Conditional-loading-of-code-in-packages-(Extensions))
+to have `Makie` as a dependency, not `MakieCore` or any of the Makie backends.
+
+You'll have to define and export your full recipe functions in your main package,
+for example:
+
+```julia
+module SomePackage
+
+export someplot
+export someplot!
+
+# functions with no methods
+function someplot end
+function someplot! end
+
+end # module
+```
+
+and then your Makie extension package will add methods to `someplot!`.
+
+```julia
+module MakieExtension
+
+using SomePackage
+import SomePackage: someplot, someplot!
+
+Makie.convert_single_argument(v::SomeVector) = v.v
+
+@recipe(SomePlot) do scene
+    Theme()
+end
+
+function Makie.plot!(p::SomePlot)
+    lines!(p, p[1])
+    scatter!(p, p[1])
+    return p
+end
+
+end # module
+```
+
+See the linked example above for more functionalities
+such as accommodating for both extensions and `Requires.jl`,
+or providing error hints for plotting functions that don't yet have methods,
+or setting up your `Project.toml`.