Prepare for first release

Author: Philip Sampaio

README.md

@@ -1,20 +1,49 @@
 # ReqCH
 
-A Req plugin for ClickHouse. 
+[![Docs](https://img.shields.io/badge/hex.pm-docs-8e7ce6.svg)](https://hexdocs.pm/req_ch)
+[![Hex pm](http://img.shields.io/hexpm/v/req_ch.svg?style=flat&color=blue)](https://hex.pm/packages/req_ch)
 
-## Installation
+A [Req](https://github.com/wojtekmach/req) plugin for [ClickHouse](https://clickhouse.com/).
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `req_ch` to your list of dependencies in `mix.exs`:
+## Usage
+
+Assuming that you have a ClickHouse server running on localhost, this code is going to run:
 
 ```elixir
-def deps do
-  [
-    {:req_ch, "~> 0.1.0"}
-  ]
-end
+Mix.install([
+  {:req_ch, "~> 0.1.0"}
+])
+
+req = ReqCH.new(database: "system")
+
+ReqCH.query!(req, "SELECT number FROM numbers LIMIT 5").body
+# => "0\n1\n2\n3\n4\n"
+
+ReqCH.query!(req, "SELECT number FROM numbers WHERE number > {num:UInt8} LIMIT 5", [num: 12]).body
+# => "13\n14\n15\n16\n17\n"
 ```
 
+It's also possible to return `Explorer` dataframes, if the `:explorer` package is installed
+and the `:explorer` format is used:
+
+```elixir
+Mix.install([
+  {:req_ch, "~> 0.1.0"},
+  {:explorer, "~> 0.10.0"}
+])
+
+req = ReqCH.new(database: "system")
+
+ReqCH.query!(req, "SELECT number, number - 2 as less_two FROM numbers LIMIT 5", [], [format: :explorer]).body
+# => #Explorer.DataFrame<
+#   Polars[5 x 2]
+#   number u64 [0, 1, 2, 3, 4]
+#   less_two s64 [-2, -1, 0, 1, 2]
+# >
+```
+
+See the [documentation](https://hexdocs.pm/req_ch) for details.
+
 ## License
 
 Copyright (C) 2024 Dashbit

lib/req_ch.ex

@@ -29,6 +29,7 @@ defmodule ReqCH do
       This option accepts `:tsv`, `:csv`, `:json` or `:explorer` as atoms.
 
       It also accepts all formats described in the #{@formats_page} page.
+      Use plain strings for these formats.
 
       The `:explorer` format is special, and will build an Explorer dataframe
       in case the `:explorer` dependency is installed.
@@ -41,14 +42,14 @@ defmodule ReqCH do
   After setting a default database, one can make a request directly:
 
       iex> req = ReqCH.new(database: "system")
-      iex> Req.post!(req, body: "SELECT number FROM numbers LIMIT 3").body
-      1\n2\n3\n
+      iex> Req.post!(req, body: "SELECT number + 1 FROM numbers LIMIT 3").body
+      "1\\n2\\n3\\n"
 
   It's also possible to make a query using `Req.get/2`:
 
       iex> req = ReqCH.new(database: "system")
-      iex> Req.get!(req, params: [query: "SELECT number FROM numbers LIMIT 3"]).body
-      1\n2\n3\n
+      iex> Req.get!(req, params: [query: "SELECT number + 1 FROM numbers LIMIT 3"]).body
+      "1\\n2\\n3\\n"
 
   In case the server needs authentication, it's possible to use `Req` options for that.
 

mix.exs

@@ -11,23 +11,45 @@ defmodule ReqCH.MixProject do
       name: "ReqCH",
       description: "A minimal Req plugin for ClickHouse",
       start_permanent: Mix.env() == :prod,
+      preferred_cli_env: [
+        docs: :docs,
+        "hex.publish": :docs
+      ],
+      docs: docs(),
+      package: package(),
       deps: deps()
     ]
   end
 
-  # Run "mix help compile.app" to learn about applications.
   def application do
     [
       extra_applications: [:logger]
     ]
   end
 
-  # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
       {:req, "~> 0.5"},
       {:explorer, "~> 0.10", optional: true},
       {:ex_doc, ">= 0.0.0", only: :docs, runtime: false}
     ]
   end
+
+  defp package do
+    [
+      licenses: ["Apache-2.0"],
+      links: %{
+        "GitHub" => "https://github.com/livebook-dev/req_ch"
+      }
+    ]
+  end
+
+  defp docs do
+    [
+      main: "readme",
+      source_url: "https://github.com/livebook-dev/req_ch",
+      source_ref: "v#{@version}",
+      extras: ["README.md"]
+    ]
+  end
 end