doc tweaks

Author: magnetised

README.md

@@ -1,3 +1,5 @@
+# Phoenix.Sync
+
 <p>
   <br />
   <a href="https://hexdocs.pm/phoenix_sync" target="_blank">
@@ -10,8 +12,6 @@
   <br />
 </p>
 
-# Phoenix.Sync
-
 [![Hex.pm](https://img.shields.io/hexpm/v/phoenix_sync.svg)](https://hex.pm/packages/phoenix_sync)
 [![Documentation](https://img.shields.io/badge/docs-hexdocs-green)](https://hexdocs.pm/phoenix_sync)
 [![License](https://img.shields.io/badge/license-Apache_2.0-green)](./LICENSE)
@@ -176,8 +176,8 @@ end
 
 # config/config.exs
 config :phoenix_sync,
-  mode: :embedded,
   env: config_env(),
+  mode: :embedded,
   repo: MyApp.Repo
 
 # application.ex
@@ -202,8 +202,8 @@ end
 
 # config/config.exs
 config :phoenix_sync,
-  mode: :http,
   env: config_env(),
+  mode: :http,
   url: "https://api.electric-sql.cloud",
   credentials: [
     secret: "...",    # required
@@ -233,8 +233,8 @@ end
 
 # config/config.exs
 config :phoenix_sync,
-  mode: :http,
   env: config_env(),
+  mode: :http,
   http: [
     port: 3000,
   ],
@@ -272,14 +272,14 @@ end
 
 # config/dev.exs
 config :phoenix_sync,
-  mode: :embedded,
   env: config_env(),
+  mode: :embedded,
   repo: MyApp.Repo
 
 # config/test.esx
 config :phoenix_sync,
-  mode: :http,
   env: config_env(),
+  mode: :http,
   http: [
     port: 3000,
   ],
@@ -371,4 +371,5 @@ The available options are:
 - `columns` (optional). The columns to include in the synced data. By default Electric will include all columns in the table. The column list **must** include all primary keys. E.g. `columns: ["id", "title", "amount"]`.
 - `replica` (optional). By default Electric will only send primary keys + changed columns on updates. Set `replica: :full` to receive the full row, not just the changed columns.
 
-See the [Electric Shapes guide](https://electric-sql.com/docs/guides/shapes) for more information.
+See the [Electric Shapes guide](https://electric-sql.com/docs/guides/shapes) for more information.
+

lib/phoenix/sync.ex

@@ -1,58 +1,4 @@
 defmodule Phoenix.Sync do
-  @moduledoc """
-  Wrappers to ease integration of [Electric’s Postgres syncing
-  service](https://electric-sql.com) with [Phoenix
-  applications](https://www.phoenixframework.org/).
-
-  There are currently 2 integration modes: [`Phoenix.LiveView`
-  streams](#module-phoenix-liveview-streams) and [configuration
-  gateway](#module-configuration-gateway).
-
-  ## Phoenix.LiveView Streams
-
-  `Phoenix.Sync.LiveView.sync_stream/4` integrates with
-  [`Phoenix.LiveView.stream/4`](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html#stream/4)
-  and provides a live updating collection of items.
-
-  ## Configuration Gateway
-
-  Using `Phoenix.Sync.Plug` you can create endpoints that
-  return configuration information for your Electric Typescript clients. See
-  [that module's documentation](`Phoenix.Sync.Plug`) for
-  more information.
-
-  ## Installation
-
-  Add `phoenix_sync` to your application dependencies:
-
-      def deps do
-        [
-          {:phoenix_sync, "~> 0.1"}
-        ]
-      end
-
-  ## Configuration
-
-  In your `config/config.exs` or `config/runtime.exs` you **must** configure the
-  client for the Electric streaming API:
-
-      import Config
-
-      config :phoenix_sync, Electric.Client,
-        # one of `base_url` or `endpoint` is required
-        base_url: System.get_env("ELECTRIC_URL", "http://localhost:3000"),
-        # endpoint: System.get_env("ELECTRIC_ENDPOINT", "http://localhost:3000/v1/shape"),
-        # optional
-        database_id: System.get_env("ELECTRIC_DATABASE_ID", nil)
-
-  See the documentation for [`Electric.Client.new/1`](`Electric.Client.new/1`)
-  for information on the client configuration.
-
-  ## Embedding Electric
-
-  **TODO**
-  """
-
   alias Electric.Client.ShapeDefinition
 
   @shape_keys [:namespace, :where, :columns]
@@ -73,31 +19,10 @@ defmodule Phoenix.Sync do
   @type param_overrides :: [param_override()]
 
   defdelegate plug_opts(), to: Phoenix.Sync.Application
-  @doc false
-  defdelegate plug_opts(opts), to: Phoenix.Sync.Application
-
-  @doc """
-  Create a new `Electric.Client` instance based on the application config.
-
-  To connect your live streams to an externally hosted Electric instance over
-  HTTP, configure your app with the URL of the Electric server:
 
-    # dev.exs
-    config :phoenix_sync, Electric.Client,
-      base_url: "http://localhost:3000"
+  defdelegate client!(), to: Phoenix.Sync.Client, as: :new!
 
-  If Electric is installed as a dependency of your app, and you wish to connect
-  your live streams to this internal application, then you don't need to configure
-  anything -- `client!/0` will return an `Electric.Client` instance configured to
-  data directly from the running Electric application.
-
-  See [`Electric.Client.new/1`](`Electric.Client.new/1`) for the available
-  options.
-
-  """
-  defdelegate client!, to: Phoenix.Sync.Client, as: :new!
-
-  @doc """
+  _ = """
   Use request query parameters to create a `Electric.Client.ShapeDefinition`.
 
   Useful when creating authorization endpoints that validate a user's access to
@@ -149,9 +74,10 @@ defmodule Phoenix.Sync do
       {:ok, %Electric.Client.ShapeDefinition{table: "things"}}
 
   """
+
+  @doc false
   @spec shape_from_params(Plug.Conn.t() | Plug.Conn.params(), overrides :: param_overrides()) ::
           {:ok, Electric.Client.ShapeDefinition.t()} | {:error, String.t()}
-
   def shape_from_params(conn_or_map, overrides \\ [])
 
   def shape_from_params(%Plug.Conn{} = conn, overrides) do

lib/phoenix/sync/client.ex

@@ -28,7 +28,7 @@ defmodule Phoenix.Sync.Client do
 
   This client can then generate streams for use in your Elixir applications:
 
-      client = Phoenix.Sync.Client.new()
+      {:ok, client} = Phoenix.Sync.Client.new()
       stream = Electric.Client.stream(client, Todos.Todo)
       for msg <- stream, do: IO.inspect(msg)
 
@@ -40,6 +40,14 @@ defmodule Phoenix.Sync.Client do
     apply(adapter, :client, [env, opts])
   end
 
+  @doc """
+  Create a new sync client based on the application configuration or raise if
+  the config is invalid.
+
+      client = Phoenix.Sync.Client.new!()
+
+  See `new/0`.
+  """
   def new! do
     case new() do
       {:ok, client} ->
@@ -50,6 +58,14 @@ defmodule Phoenix.Sync.Client do
     end
   end
 
+  @doc """
+  Create a new sync client based on the given opts or raise if
+  the config is invalid.
+
+      client = Phoenix.Sync.Client.new!(mode: :embedded)
+
+  See `new/1`.
+  """
   def new!(opts) do
     case new(opts) do
       {:ok, client} ->
@@ -95,6 +111,7 @@ defmodule Phoenix.Sync.Client do
     stream(shape, stream_opts, nil)
   end
 
+  @doc false
   def stream(shape, stream_opts, sync_opts) do
     client = new!(sync_opts)
     {shape, shape_stream_opts} = resolve_shape(shape)

lib/phoenix/sync/electric.ex

@@ -15,7 +15,7 @@ defmodule Phoenix.Sync.Electric do
   Before configuring your router, you must install and configure the
   `:phoenix_sync` application.
 
-  See the documentation for [embedding electric](`Phoenix.Sync`) for
+  See the documentation for [embedding electric](readme.html#installation-and-configuration) for
   details on embedding Electric into your Elixir application.
 
   ## Plug Integration

lib/phoenix/sync/live_view.ex

@@ -346,7 +346,7 @@ defmodule Phoenix.Sync.LiveView do
     component_event(component: component, event: event)
   end
 
-  @doc """
+  _ = """
   Embed client configuration for a shape into your HTML.
 
       <Phoenix.Sync.LiveView.electric_client_configuration
@@ -396,6 +396,8 @@ defmodule Phoenix.Sync.LiveView do
         );
       </script>
   """
+
+  @doc false
   attr :shape, :any, required: true, doc: "The Ecto query (or schema module) to subscribe to"
 
   attr :key, :string,

lib/phoenix/sync/plug.ex

@@ -1,5 +1,6 @@
 defmodule Phoenix.Sync.Plug do
-  @moduledoc """
+  @moduledoc false
+  _ = """
   Provides an configuration endpoint for use in your Phoenix applications.
 
   Rather than configuring your [Electric Typescript

lib/phoenix/sync/router.ex

@@ -6,16 +6,42 @@ defmodule Phoenix.Sync.Router do
   ## Phoenix Integration
 
   When using within a Phoenix application, you should just import the macros
-  defined here
+  defined here in your `Phoenix.Router` module:
 
-      import #{__MODULE__}
+      defmodule MyAppWeb.Router do
+        use Phoenix.Router
+
+        import #{__MODULE__}
+
+        scope "/shapes" do
+          sync "/all-todos", MyApp.Todos.Todo
+
+          sync "/pending-todos", MyApp.Todos.Todo,
+            where: "completed = false"
+        end
+      end
 
   ## Plug Integration
 
-  Within Plug applications you need to do a little more work.
+  Within your `Plug.Router` module, `use #{__MODULE__}` and then 
+  add your `sync` routes:
+
+      defmodule MyApp.Plug.Router do
+        use Plug.Router, copy_opts_to_assign: :options
+        use #{__MODULE__}
+
+        plug :match
+        plug :dispatch
+
+        sync "/shapes/all-todos", MyApp.Todos.Todo
 
-  TODO
+        sync "/shapes/pending-todos", MyApp.Todos.Todo,
+          where: "completed = false"
+      end
 
+  You **must** use the `copy_opts_to_assign` option in `Plug.Router` in order
+  for the `sync` macro to get the configuration defined in your
+  `application.ex` [`start/2`](`c:Application.start/2`) callback.
   """
 
   import Phoenix.Sync.Plug.Utils
@@ -63,15 +89,9 @@ defmodule Phoenix.Sync.Router do
 
       sync "/incomplete-todos", table: "todos", where: "completed = false"
 
-  ## Options
-
-    * `:table` - (required if no schema provided) The database table to expose
-    * `:namespace` - (optional) The namespace for the table
-    * `:where` - (optional) The where clause to apply to the data
-    * `:columns` - (optional) Subset of table columns to include in the streamed data (default all columns)
-    * `:storage` - (optional) Storage configuration
-    * `:replica` - (optional) Replication strategy
 
+  See [the section on Shape definitions](readme.html#shape-definitions) for
+  more details on keyword-based shapes.
   """
   defmacro sync(path, opts) when is_list(opts) do
     route(env!(__CALLER__), path, build_definition(path, __CALLER__, opts))
@@ -82,6 +102,14 @@ defmodule Phoenix.Sync.Router do
     route(env!(__CALLER__), path, build_shape_from_query(queryable, __CALLER__, []))
   end
 
+  @doc """
+  Create a synchronization route from an `Ecto.Schema` plus shape options.
+
+      sync "/my-shape", MyApp.Todos.Todo,
+        where: "completed = false"
+
+  See `sync/2`.
+  """
   # e.g. shape "/path", Ecto.Query.from(t in MyTable), replica: :full
   defmacro sync(path, queryable, opts) when is_tuple(queryable) and is_list(opts) do
     route(env!(__CALLER__), path, build_shape_from_query(queryable, __CALLER__, opts))