Deprecate export functions in favour of :vega_lite_convert (#82)

Author: jonatanklosko

lib/vega_lite.ex

@@ -99,6 +99,12 @@ defmodule VegaLite do
   `axis: [label_angle: -45]`, this library will automatically
   rewrite it `labelAngle`, which is the name used by the VegaLite
   specification.
+
+  ## Export
+
+  `VegaLite` graphics can be exported into various formats, such as
+  SVG, PNG and PDF thorugh the [`:vega_lite_convert`](https://hexdocs.pm/vega_lite_convert)
+  package.
   """
 
   @schema_url "https://vega.github.io/schema/vega-lite/v5.json"

lib/vega_lite/export.ex

@@ -1,40 +1,10 @@
+# TODO: remove on v1.0
 defmodule VegaLite.Export do
-  @moduledoc """
-  Various export methods for a `VegaLite` specification.
-
-  All of the export functions depend on the `:jason` package.
-  Additionally the PNG, SVG and PDF exports rely on npm packages,
-  so you will need Node.js, `npm`, and the following dependencies:
-
-  ```console
-  $ npm install -g vega vega-lite canvas
-  ```
-
-  Alternatively you can install the dependencies in a local directory:
-
-  ```console
-  $ npm install vega vega-lite canvas
-  ```
-  """
+  @moduledoc false
 
   alias VegaLite.Utils
 
-  @doc """
-  Saves a `VegaLite` specification to file in one of
-  the supported formats.
-
-  ## Options
-
-    * `:format` - the format to export the graphic as,
-      must be either of: `:json`, `:html`, `:png`, `:svg`, `:pdf`.
-      By default the format is inferred from the file extension.
-
-    * `:local_npm_prefix` - a relative path pointing to a local npm project directory
-      where the necessary npm packages are installed. For instance, in Phoenix projects
-      you may want to pass `local_npm_prefix: "assets"`. By default the npm packages
-      are searched for in the current directory and globally.
-
-  """
+  @deprecated "Use VegaLite.Convert.save!/3 in from the :vega_lite_convert package instead"
   @spec save!(VegaLite.t(), binary(), keyword()) :: :ok
   def save!(vl, path, opts \\ []) do
     {format, opts} =
@@ -69,9 +39,7 @@ defmodule VegaLite.Export do
 
   @compile {:no_warn_undefined, {Jason, :encode!, 1}}
 
-  @doc """
-  Returns the underlying Vega-Lite specification as JSON.
-  """
+  @deprecated "Use VegaLite.Convert.to_json/1 in from the :vega_lite_convert package instead"
   @spec to_json(VegaLite.t()) :: String.t()
   def to_json(vl) do
     Utils.assert_jason!("to_json/1")
@@ -81,12 +49,7 @@ defmodule VegaLite.Export do
     |> Jason.encode!()
   end
 
-  @doc """
-  Builds an HTML page that renders the given graphic.
-
-  The HTML page loads necessary JavaScript dependencies from a CDN
-  and then renders the graphic in a root element.
-  """
+  @deprecated "Use VegaLite.Convert.to_html/1 in from the :vega_lite_convert package instead"
   @spec to_html(VegaLite.t()) :: binary()
   def to_html(vl) do
     json = to_json(vl)
@@ -113,62 +76,26 @@ defmodule VegaLite.Export do
     """
   end
 
+  @doc false
+  def to_html_no_deprecation(vl), do: to_html(vl)
+
   defp escape_double_quotes(json) do
     String.replace(json, ~s{"}, ~s{\\"})
   end
 
-  @doc """
-  Renders the given graphic as a PNG image and returns
-  its binary content.
-
-  Relies on the `npm` packages mentioned above.
-
-  ## Options
-
-    * `:local_npm_prefix` - a relative path pointing to a local npm project directory
-      where the necessary npm packages are installed. For instance, in Phoenix projects
-      you may want to pass `local_npm_prefix: "assets"`. By default the npm packages
-      are searched for in the current directory and globally.
-
-  """
+  @deprecated "Use VegaLite.Convert.to_png/1 in from the :vega_lite_convert package instead"
   @spec to_png(VegaLite.t(), keyword()) :: binary()
   def to_png(vl, opts \\ []) do
     node_convert(vl, "png", "to_png/1", opts)
   end
 
-  @doc """
-  Renders the given graphic as an SVG image and returns
-  its binary content.
-
-  Relies on the `npm` packages mentioned above.
-
-  ## Options
-
-    * `:local_npm_prefix` - a relative path pointing to a local npm project directory
-      where the necessary npm packages are installed. For instance, in Phoenix projects
-      you may want to pass `local_npm_prefix: "assets"`. By default the npm packages
-      are searched for in the current directory and globally.
-
-  """
+  @deprecated "Use VegaLite.Convert.to_svg/1 in from the :vega_lite_convert package instead"
   @spec to_svg(VegaLite.t(), keyword()) :: binary()
   def to_svg(vl, opts \\ []) do
     node_convert(vl, "svg", "to_svg/1", opts)
   end
 
-  @doc """
-  Renders the given graphic into a PDF and returns its
-  binary content.
-
-  Relies on the `npm` packages mentioned above.
-
-  ## Options
-
-    * `:local_npm_prefix` - a relative path pointing to a local npm project directory
-      where the necessary npm packages are installed. For instance, in Phoenix projects
-      you may want to pass `local_npm_prefix: "assets"`. By default the npm packages
-      are searched for in the current directory and globally.
-
-  """
+  @deprecated "Use VegaLite.Convert.to_pdf/1 in from the :vega_lite_convert package instead"
   @spec to_pdf(VegaLite.t(), keyword()) :: binary()
   def to_pdf(vl, opts \\ []) do
     node_convert(vl, "pdf", "to_pdf/1", opts)

lib/vega_lite/viewer.ex

@@ -1,25 +1,14 @@
+# TODO: remove on v1.0
 defmodule VegaLite.Viewer do
-  @moduledoc """
-  Graphics rendering using Erlang's `:wx` bindings.
+  @moduledoc false
 
-  This method is useful for viewing graphics in scripts
-  and IEx sessions. Note it requires Erlang/OTP 24+ with
-  a recent WxWidgets installation with webview support.
-  """
-
-  @doc """
-  Renders a `VegaLite` specification in GUI window widget.
-
-  Requires Erlang compilation to include the `:wx` module.
-  """
+  @deprecated "Use VegaLite.Convert.open_viewer/1 in from the :vega_lite_convert package instead"
   @spec show(VegaLite.t()) :: :ok | :error
   def show(vl) do
     with {:ok, _pid} <- start_wx_viewer(vl), do: :ok
   end
 
-  @doc """
-  Same as `show/1`, but blocks until the window widget is closed.
-  """
+  @deprecated "Use VegaLite.Convert.open_viewer_and_wait/1 in from the :vega_lite_convert package instead"
   @spec show_and_wait(VegaLite.t()) :: :ok | :error
   def show_and_wait(vl) do
     with {:ok, pid} <- start_wx_viewer(vl) do
@@ -33,7 +22,7 @@ defmodule VegaLite.Viewer do
 
   defp start_wx_viewer(vl) do
     vl
-    |> VegaLite.Export.to_html()
+    |> VegaLite.Export.to_html_no_deprecation()
     |> VegaLite.WxViewer.start()
   end
 end

lib/vega_lite/wx_viewer.ex

@@ -1,3 +1,4 @@
+# TODO: remove on v1.0
 defmodule VegaLite.WxViewer do
   @moduledoc false