improvement: update getting started guide and document generators

README.md

@@ -81,6 +81,7 @@ Welcome! Here you will find everything you need to know to get started with and
 ### Development
 
 - [Project Structure](documentation/topics/development/project-structure.md)
+- [Generators](documentation/topics/development/generators.md)
 - [Testing](documentation/topics/development/testing.md)
 - [Development Utilities](documentation/topics/development/development-utilities.md)
 - [Upgrading to 3.0](documentation/topics/development/upgrading-to-3.0.md)

documentation/topics/development/generators.md

@@ -0,0 +1,16 @@
+# Generators
+
+Ash comes with multiple generators, packages as mix tasks, to help you generate and make modifications to your applications.
+
+See the documentation for each mix task for more information. What is presented here is merely an overview.
+
+## Generators
+
+- `mix ash.gen.resource` - Generates a new `Ash.Resource`
+- `mix ash.gen.domain` - Generates a new `Ash.Domain`
+- `mix ash.gen.enum` - Generates a new `Ash.Type.Enum`
+- `mix ash.gen.base_resource` - Generates a new base resource.
+
+## Patchers
+
+- `mix ash.patch.extend` - Adds an extension or extensions to a domain or resource.

documentation/tutorials/get-started.md

@@ -40,6 +40,54 @@ The actions we will be able to take on these resources include:
 
 ### Create a new project
 
+#### Using Igniter
+
+First, to use `mix igniter.new`, the archive must be installed.
+
+To install it, run
+
+```bash
+mix archive.install hex igniter_new
+```
+
+Then, create a new project:
+
+```elixir
+mix igniter.new helpdesk --install ash && cd helpdesk
+```
+
+It is a good idea to make it a git repository and commit the initial project. You'll be able to see what changes we made, and can save your changes once we're done.
+
+```bash
+# Run in your terminal
+git init
+git add -A
+git commit -m "first commit"
+git branch -M main
+```
+
+Open the project in your text editor, and we'll get started.
+
+You can skip to [Building your first Ash Domain](#building-your-first-ash-domain).
+
+> ### Want to skip to the end? {: .warning}
+>
+> Add the `--example` flag to get the example code add directly to your app!
+>
+> ```bash
+> mix igniter.new helpdesk --install ash --example
+> ```
+>
+> Already know you want to use `AshPostgres`? Use the `--extend` argument.
+>
+> ```bash
+> mix igniter.new helpdesk --install ash --example --extend postgres`
+> ```
+>
+> If you generate this code, you can browse the rest of the guide, but the code shown will already be present in your application 🥳
+
+#### Using Mix
+
 We first create a new project with the `--sup` flag to add a supervision tree. This will be necessary for other follow-up tutorials.
 
 ```bash

lib/mix/tasks/gen/ash.gen.base_resource.ex

@@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.BaseResource do
   @moduledoc """
   Generates a base resource
 
-  For example: `mix ash.gen.base_resource The.Resource.Name`
+  ## Example
+
+  ```bash
+  mix ash.gen.base_resource MyApp.Resource
+  ```
   """
   @shortdoc "Generates a base resource. This is a module that you can use instead of `Ash.Resource`, for consistency."
   use Igniter.Mix.Task

lib/mix/tasks/gen/ash.gen.domain.ex

@@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Domain do
   @moduledoc """
   Generates an Ash.Domain
 
-  For example: `mix ash.gen.domain The.Domain`
+  ## Example
+
+  ```bash
+  mix ash.gen.domain MyApp.Accounts
+  ```
   """
 
   @shortdoc "Generates an Ash.Domain"

lib/mix/tasks/gen/ash.gen.enum.ex

@@ -2,7 +2,11 @@ defmodule Mix.Tasks.Ash.Gen.Enum do
   @moduledoc """
   Generates an Ash.Type.Enum
 
-  For example `mix ash.gen.enum The.Enum.Name list,of,values`
+  ## Example
+
+  ```bash
+  mix ash.gen.enum MyApp.Support.Ticket.Types.Status open,closed --short-name ticket_status
+  ```
 
   ## Options
 

lib/mix/tasks/gen/ash.gen.resource.ex

@@ -1,11 +1,20 @@
 defmodule Mix.Tasks.Ash.Gen.Resource do
   @moduledoc """
-  Generate and configures an Ash.Resource.
-
-  ## What changes take place?
+  Generate and configure an Ash.Resource.
 
   If the domain does not exist, we create it. If it does, we add the resource to it if it is not already present.
 
+  ## Example
+
+  ```bash
+  mix ash.gen.resource Helpdesk.Support.Ticket \
+    --default-actions read
+    --uuid-primary-key id
+    --attribute subject:string:required:public
+    --relationship belongs_to:representative:Helpdesk.Support.Representative \
+    --extend postgres,graphql
+  ```
+
   ## Options
 
   * `--attribute` or `-a` - An attribute or comma separated list of attributes to add, as `name:type`. Modifiers: `primary_key`, `public`, and `required`. i.e `-a name:string:required`
@@ -18,7 +27,7 @@ defmodule Mix.Tasks.Ash.Gen.Resource do
   * `--base` or `-b` - The base module to use for the resource. i.e `-b Ash.Resource`. Requires that the module is in `config :your_app, :base_resources`
   """
 
-  @shortdoc "Generate an Ash.Resource."
+  @shortdoc "Generate and configure an Ash.Resource."
   use Igniter.Mix.Task
 
   @impl Igniter.Mix.Task

lib/mix/tasks/patch/ash.patch.extend.ex

@@ -2,7 +2,29 @@ defmodule Mix.Tasks.Ash.Patch.Extend do
   @moduledoc """
   Adds an extension or extensions to the domain/resource
 
-  For example: `mix ash.patch.extend My.Domain.Resource Ash.Policy.Authorizer`
+  Extensions can either be a fully qualified module name, or one of the following list, based on the thing being extended
+
+  ### Ash.Domain
+
+  - `json_api` - `AshJsonApi.Domain`
+  - `graphql` - `AshGraphql.Domain`
+
+  ### Ash.Resource
+
+  - `postgres` - `AshPostgres.DataLayer`
+  - `sqlite` - `AshSqlite.DataLayer`
+  - `mysql` - `AshMysql.DataLayer`
+  - `ets` - `Ash.DataLayer.Ets`
+  - `mnesia` - `Ash.DataLayer.Mnesia`
+  - `embedded` - `data_layer: :embedded`
+  - `json_api` - `AshJsonApi.Resource`
+  - `graphql` - `AshGraphql.Resource`
+
+  ## Example
+
+  ```bash
+  mix ash.patch.extend My.Domain.Resource postgres,Ash.Policy.Authorizer
+  ```
   """
   @shortdoc "Adds an extension or extensions to the given domain/resource"
   require Igniter.Code.Common

mix.exs

@@ -72,6 +72,7 @@ defmodule Ash.MixProject do
         "documentation/topics/advanced/multitenancy.md",
         "documentation/topics/advanced/writing-extensions.md",
         "documentation/topics/development/project-structure.md",
+        "documentation/topics/development/generators.md",
         "documentation/topics/development/error-handling.md",
         "documentation/topics/development/testing.md",
         "documentation/topics/development/development-utilities.md",