From 871d44402d2f6aa6be043485db704cd44223479d Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Sat, 14 Nov 2020 21:28:06 +0800 Subject: [PATCH 1/4] Misc doc changes List of changes: - Set readme as default html doc page - Use common source url - Always get latest greatest ex_doc version - Badges and more badges! - Fix indentation --- README.md | 113 +++++++++++++++++++++++++++--------------------------- mix.exs | 16 ++++---- 2 files changed, 64 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 96c8daa..64e3d46 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,11 @@ # EctoVista - PostgreSQL views for Ecto -![Elixir CI](https://github.com/flowerett/ecto_vista/workflows/Elixir%20CI/badge.svg) +[![Elixir CI](https://github.com/flowerett/ecto_vista/workflows/Elixir%20CI/badge.svg)](https://github.com/flowerett/ecto_vista/actions) +[![Module Version](https://img.shields.io/hexpm/v/ecto_vista.svg)](https://hex.pm/packages/ecto_vista) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ecto_vista/) +[![Total Download](https://img.shields.io/hexpm/dt/ecto_vista.svg)](https://hex.pm/packages/ecto_vista) +[![License](https://img.shields.io/hexpm/l/ecto_vista.svg)](https://github.com/yyy/ecto_vista/blob/master/LICENSE) +[![Last Updated](https://img.shields.io/github/last-commit/flowerett/ecto_vista.svg)](https://github.com/flowerett/ecto_vista/commits/master) ![Landscape](https://pp.userapi.com/c1111/u5935491/11475271/x_d17f8ffd.jpg) @@ -10,8 +15,7 @@ Inspired by [scenic](https://github.com/scenic-views/scenic) library for ActiveR ## Installation -If [available in Hex](https://hex.pm/docs/publish), the package can be installed -by adding `ecto_vista` to your list of dependencies in `mix.exs`: +Add `ecto_vista` to your list of dependencies in `mix.exs`: ```elixir def deps do @@ -25,63 +29,65 @@ end 1. Add `ecto_vista` to your list of dependencies in `mix.exs` and run: -``` -mix deps.get -``` + ``` + mix deps.get + ``` 2. Generate your migration for the view, put the view definition like the one below inside `change` or `up` method: -``` -execute(""" - CREATE MATERIALIZED VIEW catalog_v1 AS - SELECT c.*, count(p.id) AS product_count - FROM categories c - LEFT JOIN products p ON c.id = p.category_id - GROUP BY c.id - ; -""") -``` + ``` + execute(""" + CREATE MATERIALIZED VIEW catalog_v1 AS + SELECT c.*, count(p.id) AS product_count + FROM categories c + LEFT JOIN products p ON c.id = p.category_id + GROUP BY c.id + ; + """) + ``` 3. Use `EctoVista` module in your Ecto schema: -``` -def App.Catalog do - use Ecto.Schema - use EctoVista, - repo: App.Repo - table_name: "catalog" - - schema @table_name do - field(:name, :string) - field(:product_count, :integer) - end -end -``` - -The `@table_name` will be defined in macro as `{table_name}_v{version}` (version is 1 by default) -This naming convention facilitates 0-downtime view updates and will be handled automagically in future versions. - -If you need to update the view, generate a new migration and then just update the version number in the schema definition: - -``` -def App.Catalog do - use Ecto.Schema - use EctoVista, - repo: App.Repo - table_name: "catalog" - version: 2 - - ... -end -``` + ``` + def App.Catalog do + use Ecto.Schema + use EctoVista, + repo: App.Repo + table_name: "catalog" + + schema @table_name do + field(:name, :string) + field(:product_count, :integer) + end + end + ``` + + The `@table_name` will be defined in macro as `{table_name}_v{version}` + (version is 1 by default). This naming convention facilitates 0-downtime view + updates and will be handled automagically in future versions. + + If you need to update the view, generate a new migration and then just + update the version number in the schema definition: + + ``` + def App.Catalog do + use Ecto.Schema + use EctoVista, + repo: App.Repo + table_name: "catalog" + version: 2 + + ... + end + ``` 4. Don't forget to refresh your materialized view to see data: -``` -iex> Catalog.refresh -:ok -``` + ``` + iex> Catalog.refresh + :ok + ``` ## Roadmap @@ -95,12 +101,7 @@ iex> Catalog.refresh - [ ] Support all options to refresh and create views - [ ] Implement automatic view versioning for migration -## Docs - -Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc) -and published on [HexDocs](https://hexdocs.pm). Once published, the docs can -be found at [https://hexdocs.pm/ecto_vista](https://hexdocs.pm/ecto_vista). - ## License The source code is under the Apache 2 License. +Copyright (c) 2019- Nick Chernyshev. diff --git a/mix.exs b/mix.exs index 71e974e..20ca7cd 100644 --- a/mix.exs +++ b/mix.exs @@ -1,6 +1,7 @@ defmodule EctoVista.MixProject do use Mix.Project + @source_url "https://github.com/flowerett/ecto_vista" @version "0.2.0" def project do @@ -22,13 +23,11 @@ defmodule EctoVista.MixProject do # Docs name: "EctoVista", - source_url: "https://github.com/flowerett/ecto_vista", - homepage_url: "https://github.com/flowerett/ecto_vista", + homepage_url: @source_url, docs: docs() ] end - # Run "mix help compile.app" to learn about applications. def application do [ extra_applications: [:logger] @@ -47,7 +46,6 @@ defmodule EctoVista.MixProject do ] end - # Run "mix help deps" to learn about dependencies. defp deps do [ {:ecto, "~> 3.5"}, @@ -59,7 +57,7 @@ defmodule EctoVista.MixProject do {:dialyxir, "~> 1.0", only: [:dev, :test], runtime: false}, # Docs dependencies - {:ex_doc, "~> 0.23", only: :dev, runtime: false}, + {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}, {:inch_ex, "~> 2.0", only: :dev, runtime: false} ] end @@ -68,16 +66,16 @@ defmodule EctoVista.MixProject do [ maintainers: ["Nick Chernyshev"], licenses: ["Apache 2.0"], - links: %{"GitHub" => "https://github.com/flowerett/ecto_vista"}, + links: %{"GitHub" => @source_url}, files: ~w(.formatter.exs mix.exs README.md lib) ] end defp docs do [ - main: "EctoVista", - extras: ["README.md"], - source_url: "https://github.com/flowerett/ecto_vista" + main: "readme", + source_url: @source_url, + extras: ["README.md"] ] end end From 0113b5a8ab1743190fc01003c2e1971bf42ded54 Mon Sep 17 00:00:00 2001 From: Nick C Date: Sun, 15 Nov 2020 14:00:37 +0100 Subject: [PATCH 2/4] Update README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 64e3d46..24c85dd 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Module Version](https://img.shields.io/hexpm/v/ecto_vista.svg)](https://hex.pm/packages/ecto_vista) [![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ecto_vista/) [![Total Download](https://img.shields.io/hexpm/dt/ecto_vista.svg)](https://hex.pm/packages/ecto_vista) -[![License](https://img.shields.io/hexpm/l/ecto_vista.svg)](https://github.com/yyy/ecto_vista/blob/master/LICENSE) +[![License](https://img.shields.io/hexpm/l/ecto_vista.svg)](https://github.com/flowerett/ecto_vista/blob/master/LICENSE.md) [![Last Updated](https://img.shields.io/github/last-commit/flowerett/ecto_vista.svg)](https://github.com/flowerett/ecto_vista/commits/master) ![Landscape](https://pp.userapi.com/c1111/u5935491/11475271/x_d17f8ffd.jpg) @@ -104,4 +104,4 @@ inside `change` or `up` method: ## License The source code is under the Apache 2 License. -Copyright (c) 2019- Nick Chernyshev. +Copyright ©2019 Nikolai Chernyshev From 97bd53ce1e52c364ef1500ca262e2e5f8d0757f1 Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Tue, 17 Nov 2020 01:31:31 +0800 Subject: [PATCH 3/4] Remove duplicated content --- README.md | 135 ++++++++++++++++++++++++---------------------- lib/ecto_vista.ex | 65 +++------------------- mix.exs | 2 +- 3 files changed, 80 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index 24c85dd..dbe7ff8 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Inspired by [scenic](https://github.com/scenic-views/scenic) library for ActiveR ## Installation -Add `ecto_vista` to your list of dependencies in `mix.exs`: +Add `:ecto_vista` to your list of dependencies in `mix.exs`: ```elixir def deps do @@ -25,69 +25,76 @@ def deps do end ``` -## Basic Usage - -1. Add `ecto_vista` to your list of dependencies in `mix.exs` and run: - - ``` - mix deps.get - ``` - -2. Generate your migration for the view, put the view definition like the one below -inside `change` or `up` method: - - ``` - execute(""" - CREATE MATERIALIZED VIEW catalog_v1 AS - SELECT c.*, count(p.id) AS product_count - FROM categories c - LEFT JOIN products p ON c.id = p.category_id - GROUP BY c.id - ; - """) - ``` - -3. Use `EctoVista` module in your Ecto schema: - - ``` - def App.Catalog do - use Ecto.Schema - use EctoVista, - repo: App.Repo - table_name: "catalog" - - schema @table_name do - field(:name, :string) - field(:product_count, :integer) - end - end - ``` - - The `@table_name` will be defined in macro as `{table_name}_v{version}` - (version is 1 by default). This naming convention facilitates 0-downtime view - updates and will be handled automagically in future versions. - - If you need to update the view, generate a new migration and then just - update the version number in the schema definition: - - ``` - def App.Catalog do - use Ecto.Schema - use EctoVista, - repo: App.Repo - table_name: "catalog" - version: 2 - - ... - end - ``` - -4. Don't forget to refresh your materialized view to see data: - - ``` - iex> Catalog.refresh - :ok - ``` + + +## Using EctoVista + +To use `EctoVista`, you need to add `use EctoVista` to your Elixir files. This +gives you access to the functions and macros defined in the module. + +```elixir +def App.Catalog do + use Ecto.Schema + use EctoVista, + repo: App.Repo + table_name: "catalog" + + schema @table_name do + field(:name, :string) + field(:product_count, :integer) + end +end +``` + +The `@table_name` will be defined in macro as `{table_name}_v{version}` +(version is 1 by default) This naming convention facilitates 0-downtime view +updates and will be handled automagically in future versions. + +## Generating Views + +Views can be generated via regular migration, just put the definition inside +`change` or `up` migration methods. + +For the schema definition like the one above, view can be generated as: + +```elixir +execute(\"\"\" + CREATE MATERIALIZED VIEW catalog_v1 AS + SELECT c.*, count(p.id) AS product_count + FROM categories c + LEFT JOIN products p ON c.id = p.category_id + GROUP BY c.id + ; +\"\"\") +``` + +## Updating Views + +If you need to update the view, generate a new migration and then just update +the version number in the schema definition: + +```elixir +def App.Catalog do + use Ecto.Schema + use EctoVista, + repo: App.Repo + table_name: "catalog" + version: 2 + + ... +end +``` + +## Refreshing Views + +Use the `refresh/0` function. It will run `REFRESH MATERIALIZED VIEW +[view_name];` query. + +```elixir +iex> Catalog.refresh +:ok +``` + ## Roadmap diff --git a/lib/ecto_vista.ex b/lib/ecto_vista.ex index 43b1813..8df36ea 100644 --- a/lib/ecto_vista.ex +++ b/lib/ecto_vista.ex @@ -1,66 +1,17 @@ defmodule EctoVista do + @external_resource readme = "README.md" + @moduledoc """ Provides the macros and functions to define and manage PostgreSQL views with Ecto. - ## Using EctoVista - - To use `EctoVista`, you need to add `use EctoVista` to your Elixir - files. This gives you access to the functions and macros defined - in the module. - - example: - def App.Catalog do - use Ecto.Schema - use EctoVista, - repo: App.Repo - table_name: "catalog" - - schema @table_name do - field(:name, :string) - field(:product_count, :integer) - end - end - - The `@table_name` will be defined in macro as `{table_name}_v{version}` (version is 1 by default) - This naming convention facilitates 0-downtime view updates and will be handled automagically in future versions. - - ## Generating Views - - Views can be generated via regular migration, just put the definition inside `change` or `up` migration methods. - For the schema definition like the one above, view can be generated as: - - execute(\"\"\" - CREATE MATERIALIZED VIEW catalog_v1 AS - SELECT c.*, count(p.id) AS product_count - FROM categories c - LEFT JOIN products p ON c.id = p.category_id - GROUP BY c.id - ; - \"\"\") - - - ## Updating Views - - If you need to update the view, generate a new migration and then just update the version number in the schema definition: - - def App.Catalog do - use Ecto.Schema - use EctoVista, - repo: App.Repo - table_name: "catalog" - version: 2 - - ... - end - - ## Refreshing Views - - Use the `refresh/0` function - It will run `REFRESH MATERIALIZED VIEW [view_name];` query. + #{ + readme + |> File.read!() + |> String.split("") + |> Enum.fetch!(1) + } - iex> Catalog.refresh - :ok """ require Ecto.Query diff --git a/mix.exs b/mix.exs index 20ca7cd..1eb57c0 100644 --- a/mix.exs +++ b/mix.exs @@ -73,7 +73,7 @@ defmodule EctoVista.MixProject do defp docs do [ - main: "readme", + main: "EctoVista", source_url: @source_url, extras: ["README.md"] ] From 30640f8f745cf794e1653b15631a74eb72c5dbe7 Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Wed, 18 Nov 2020 23:56:26 +0800 Subject: [PATCH 4/4] Revise doc changes based repo owner preferences --- README.md | 3 --- lib/ecto_vista.ex | 10 ---------- mix.exs | 5 +++-- 3 files changed, 3 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index dbe7ff8..09e3c95 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,6 @@ def deps do end ``` - - ## Using EctoVista To use `EctoVista`, you need to add `use EctoVista` to your Elixir files. This @@ -94,7 +92,6 @@ Use the `refresh/0` function. It will run `REFRESH MATERIALIZED VIEW iex> Catalog.refresh :ok ``` - ## Roadmap diff --git a/lib/ecto_vista.ex b/lib/ecto_vista.ex index 8df36ea..725262e 100644 --- a/lib/ecto_vista.ex +++ b/lib/ecto_vista.ex @@ -1,17 +1,7 @@ defmodule EctoVista do - @external_resource readme = "README.md" - @moduledoc """ Provides the macros and functions to define and manage PostgreSQL views with Ecto. - - #{ - readme - |> File.read!() - |> String.split("") - |> Enum.fetch!(1) - } - """ require Ecto.Query diff --git a/mix.exs b/mix.exs index 1eb57c0..8112570 100644 --- a/mix.exs +++ b/mix.exs @@ -23,6 +23,7 @@ defmodule EctoVista.MixProject do # Docs name: "EctoVista", + source_url: @source_url, homepage_url: @source_url, docs: docs() ] @@ -73,8 +74,8 @@ defmodule EctoVista.MixProject do defp docs do [ - main: "EctoVista", - source_url: @source_url, + main: "readme", + api_reference: false, extras: ["README.md"] ] end