### Build and Install Igniter Locally

Source: https://github.com/ash-project/igniter/blob/main/installer/README.md

Follow these steps to build the igniter archive locally and then install it. Ensure any previous version is uninstalled first.

```shell
cd installer
mix archive.uninstall igniter_new
MIX_ENV=prod mix do archive.build + archive.install
```

--------------------------------

### Install Igniter from Hex

Source: https://github.com/ash-project/igniter/blob/main/installer/README.md

Use this command to install the igniter archive directly from Hex.pm.

```shell
$ mix archive.install hex igniter_new
```

--------------------------------

### Generate New Mix Project with Ash and Ecto

Source: https://github.com/ash-project/igniter/blob/main/README.md

Create a new Elixir project with Igniter, specifying multiple installations such as 'ash' and 'ecto' to be included from the start.

```bash
mix igniter.new app_name --install ash,ecto
```

--------------------------------

### Install Igniter Globally via Archive

Source: https://github.com/ash-project/igniter/blob/main/README.md

Install the Igniter archive globally to use `mix igniter.new` for generating new Elixir projects. This is an alternative to adding Igniter as a project dependency.

```bash
mix archive.install hex igniter_new
```

--------------------------------

### Best Practice: Descriptive Section Names

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Use clear and descriptive names for sections and provide helpful explanations to improve documentation clarity. This example shows setting up a formatter.

```elixir
@setup_formatter """
Configure the DSL auto-formatter. This tells the formatter to remove excess parentheses
and how to sort sections in your modules for consistency.
"""

igniter
|> Igniter.Scribe.section("Setup The Formatter", @setup_formatter, fn igniter ->
  # Implementation
end)
```

--------------------------------

### Run Igniter Upgrade in GitHub Actions

Source: https://github.com/ash-project/igniter/blob/main/documentation/upgrades.md

This example shows GitHub Actions steps to integrate `mix igniter.upgrade` for CI, leveraging Dependabot and a Git auto-commit action. It requires `fetch-depth: 0` for `actions/checkout` to access the lock file.

```yml
igniter-upgrade:
  name: mix igniter.upgrade
  runs-on: ubuntu-latest
  if: ${{inputs.igniter-upgrade}}
  permissions:
    contents: write
  steps:
    - name: Dependabot metadata
      id: dependabot-metadata
      uses: dependabot/fetch-metadata@v2
      if: github.event.pull_request.user.login == 'dependabot[bot]'
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0
        ref: ${{ github.head_ref }}
    # This uses a ".tool-version" file for languages
    # Feel free to use whatever steps you want to set up elixir
    # and run the `igniter.upgrade` mix task. Just use the same flags as shown.
    - uses: team-alembic/staple-actions/actions/mix-task@main
      with:
        task: igniter.upgrade --git-ci
    - name: Commit Changes
      uses: stefanzweifel/git-auto-commit-action@v5
      if: github.event.pull_request.user.login == 'dependabot[bot]'
      with:
        commit_message: "[dependabot skip] Apply Igniter Upgrades"
        commit_user_name: dependabot[bot]
```

--------------------------------

### Generate New Elixir Project with Igniter

Source: https://github.com/ash-project/igniter/blob/main/README.md

Use the globally installed Igniter archive to generate a new Elixir project. You can specify additional installations like 'ash' during project creation.

```bash
mix igniter.new app_name --install ash
```

--------------------------------

### Create Custom Ash Resource Generator

Source: https://github.com/ash-project/igniter/blob/main/README.md

Define a custom generator that extends the default `mix ash.gen.resource` task. This example shows how to parse the resource name, create a new module, and compose it with the original task.

```elixir
defmodule Mix.Tasks.MyApp.Gen.Resource do
  use Igniter.Mix.Task

  @impl Igniter.Mix.Task
  def igniter(igniter) do
    [resource | _] = igniter.args.argv

    resource = Igniter.Code.Module.parse(resource)
    my_special_thing = Module.concat([resource, SpecialThing])
    location = Igniter.Code.Module.proper_location(my_special_thing)

    igniter
    |> Igniter.compose_task("ash.gen.resource", igniter.args.argv)
    |> Igniter.Project.Module.create_module(my_special_thing, """
      # this is the special thing for #{inspect()}
    """)
  end
end
```

--------------------------------

### Initialize Scribe Documentation

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Use `Igniter.Scribe.start_document/4` to initialize the documentation with a title and introduction. Only the first call to this function is honored. Options like `:app_name` can be passed.

```elixir
@manual_lead_in """
This guide will walk you through the process of manually installing YourLibrary into your project.
If you are starting from scratch, you can use `mix new` or `mix igniter.new` and follow these instructions.
"""

igniter
|> Igniter.Scribe.start_document(
  "Manual Installation",
  @manual_lead_in,
  app_name: :my_app
)
```

--------------------------------

### Create Igniter Configuration File

Source: https://github.com/ash-project/igniter/blob/main/documentation/configuring-igniter.md

Run this command to generate the `.igniter.exs` file in your project root. You can execute it multiple times to update the file.

```bash
mix igniter.setup
```

--------------------------------

### Igniter.Scribe.start_document/4

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Initializes the documentation generation process with a title, introductory content, and optional configuration. This function should be called first.

```APIDOC
## `start_document/4`

Initializes the documentation with a title and introduction. Only the first call to this function is honored.

```elixir
Igniter.Scribe.start_document(igniter, title, contents, opts \ [])
```

**Parameters:**
- `igniter` - The Igniter struct
- `title` - The main title for the document (will be rendered as `# Title`)
- `contents` - Introduction text that appears after the title
- `opts` - Optional keyword list (can include `:app_name` and other options)

**Example:**

```elixir
@manual_lead_in """
This guide will walk you through the process of manually installing YourLibrary into your project.
If you are starting from scratch, you can use `mix new` or `mix igniter.new` and follow these instructions.
"""

igniter
|> Igniter.Scribe.start_document(
  "Manual Installation",
  @manual_lead_in,
  app_name: :my_app
)
```
```

--------------------------------

### Create a Documentation Section

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Use `Igniter.Scribe.section/3` to create a new section with a header, explanation, and a callback function that performs the actual changes. This function captures diffs for the documentation.

```elixir
@setup_dependencies """
Install and configure the required dependencies for YourLibrary.
This will add the necessary packages to your mix.exs file.
"""

igniter
|> Igniter.Scribe.section("Setup Dependencies", @setup_dependencies, fn igniter ->
  igniter
  |> Igniter.Scribe.patch(&Igniter.Project.Deps.add_dep(&1, {:other_library, "~> 1.0"}))
  |> Igniter.Scribe.patch(&Igniter.compose_task(&1, "other_library.install"))
end)
```

--------------------------------

### Combine Igniter with Existing Project Generators

Source: https://github.com/ash-project/igniter/blob/main/README.md

Integrate Igniter with other project generators like `mix phx.new`. Use the `--with` flag to specify the generator and `--with-args` to pass arguments to it.

```bash
mix igniter.new app_name --install ash --with phx.new --with-args="--no-ecto --no-html"
```

--------------------------------

### Generate File and Configure Project with Igniter

Source: https://github.com/ash-project/igniter/blob/main/documentation/writing-generators.md

This generator creates a new file and ensures a configuration is set in the user's config.exs. It parses module names, determines file paths, and uses Igniter's utilities for file creation and configuration updates.

```elixir
defmodule Mix.Tasks.YourLib.Gen.YourThing do
  use Igniter.Mix.Task

  @impl Igniter.Mix.Task
  def igniter(igniter) do
    [module_name | _] = igniter.args.argv

    module_name = Igniter.Project.Module.parse(module_name)
    path = Igniter.Project.Module.proper_location(igniter, module_name)
    app_name = Igniter.Project.Application.app_name(igniter)

    igniter
    |> Igniter.create_new_file(path, """
defmodule #{inspect(module_name)} do
  use YourLib.Thing

  ...some_code
end
""")
    |> Igniter.Project.Config.configure(
      "config.exs",
      app_name,
      [:list_of_things],
      [module_name],
      updater: &Igniter.Code.List.prepend_new_to_list(&1, module_name)
    )
  end
end
```

--------------------------------

### Publish igniter Package to Hex

Source: https://github.com/ash-project/igniter/blob/main/RELEASE.md

Use this command to publish the igniter package to Hex. It's typically handled by CI, but can be run manually if needed.

```elixir
mix hex.publish
```

--------------------------------

### Compose Igniter Tasks

Source: https://github.com/ash-project/igniter/blob/main/documentation/writing-generators.md

Demonstrates how to compose multiple Igniter tasks sequentially. This is useful for chaining generator actions, such as generating multiple modules or applying different configurations.

```elixir
igniter
|> Igniter.compose_task(Mix.Tasks.YourLib.Gen.YourThing, ["MyApp.MyModuleName"])
|> Igniter.compose_task(Mix.Tasks.YourLib.Gen.YourThing, ["MyApp.SomeOtherName"])
```

--------------------------------

### Generate Documentation for a Mix Task

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Use the `--scribe` option followed by the output file path to generate documentation for any Igniter mix task.

```bash
mix your.task --scribe documentation/tutorials/your-guide.md
```

--------------------------------

### Set Up a Mix Task for Scribe

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Define a mix task using `Igniter.Mix.Task` and implement the `igniter/1` callback to integrate with Igniter.Scribe. The `@shortdoc` and `@moduledoc` attributes are used for documentation.

```elixir
defmodule Mix.Tasks.YourLibrary.Install do
  @shortdoc "Installs YourLibrary into a project"

  @moduledoc """#{@shortdoc}

  ## Options

  - `--example` - Creates example resources
  """

  use Igniter.Mix.Task

  @impl Igniter.Mix.Task
  def igniter(igniter) do
    igniter
    |> Igniter.Scribe.start_document(
      "Manual Installation Guide",
      @manual_lead_in
    )
    |> add_your_sections()
  end
end
```

--------------------------------

### Move Files Based on Module Location Strategy

Source: https://github.com/ash-project/igniter/blob/main/documentation/configuring-igniter.md

Execute this command to reorganize module files according to the configured `module_location` strategy.

```bash
mix igniter.move_files
```

--------------------------------

### Basic Usage of --scribe option

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Generate documentation for any Igniter mix task by using the --scribe option followed by the desired output file path.

```APIDOC
## Basic Usage

To generate documentation for any Igniter mix task, use the `--scribe` option followed by the output file path:

```bash
mix your.task --scribe documentation/tutorials/your-guide.md
```
```

--------------------------------

### Igniter.Scribe.section/3

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Adds a new section to the generated documentation, including a header, explanatory text, and a callback function to perform specific actions.

```APIDOC
## `section/3`

Creates a new section in the documentation with a header, explanation, and the actual changes.

```elixir
Igniter.Scribe.section(igniter, header, explanation, callback)
```

**Parameters:**
- `igniter` - The Igniter struct
- `header` - The section header text
- `explanation` - Descriptive text explaining what this section does
- `callback` - A function that receives the igniter and performs the actual changes

**Example:**

```elixir
@setup_dependencies """
Install and configure the required dependencies for YourLibrary.
This will add the necessary packages to your mix.exs file.
"""

igniter
|> Igniter.Scribe.section("Setup Dependencies", @setup_dependencies, fn igniter ->
  igniter
  |> Igniter.Scribe.patch(&Igniter.Project.Deps.add_dep(&1, {:other_library, "~> 1.0"}))
  |> Igniter.Scribe.patch(&Igniter.compose_task(&1, "other_library.install"))
end)
```
```

--------------------------------

### Add Phoenix Extension to Igniter

Source: https://github.com/ash-project/igniter/blob/main/documentation/configuring-igniter.md

Use this command to add the Phoenix extension, which helps in organizing Phoenix-related modules.

```bash
mix igniter.add_extension phoenix
```

--------------------------------

### Generate Changelog and Bump Version with igniter

Source: https://github.com/ash-project/igniter/blob/main/RELEASE.md

Run this command to automatically generate a new changelog and increment the version number for the igniter package. You will be prompted to push tags to Git.

```elixir
mix git_ops.release
```

--------------------------------

### Add Igniter as Optional Dependency for Library Authors

Source: https://github.com/ash-project/igniter/blob/main/README.md

Library authors should add Igniter with `optional: true` to their `mix.exs`. This ensures Igniter is not included in end-users' production applications by default.

```elixir
 {:igniter, "~> 0.6", optional: true}
```

--------------------------------

### Apply Igniter Upgrades

Source: https://github.com/ash-project/igniter/blob/main/README.md

Manually apply Igniter upgrades, especially when moving from older versions like 0.3.x to 0.4.x. This command helps complete the upgrade process after potential issues with self-upgrades.

```bash
mix igniter.apply_upgrades igniter:0.4.0:0.5.0 package:0.1.3:0.1.4
```

--------------------------------

### Define Igniter Task Group

Source: https://github.com/ash-project/igniter/blob/main/documentation/writing-generators.md

Shows how to define a group for an Igniter Mix.Task.Info struct. Assigning a group helps Igniter manage flag disambiguation and allows for shorter, semantic option names.

```elixir
%Igniter.Mix.Task.Info{
  group: :your_package,
  ...
}
```

--------------------------------

### Handle Ambiguous Flags in Task Groups

Source: https://github.com/ash-project/igniter/blob/main/documentation/writing-generators.md

Illustrates how Igniter alerts users to ambiguous flags and provides a solution by prefixing options with the task or group name. This helps prevent conflicts when multiple tasks define the same flag.

```sh
Ambiguous flag provided `--option`.

The task or task groups `package1, package2` all define the flag `--option`.

To disambiguate, provide the arg as `--<prefix>.option`,
where `<prefix>` is the task or task group name.

For example:

`--package1.option`
```

--------------------------------

### Compose Task to Add Extension Programmatically

Source: https://github.com/ash-project/igniter/blob/main/documentation/configuring-igniter.md

For developers writing tasks, this function composes a task to add an extension, such as 'phoenix'.

```elixir
Igniter.compose_task("igniter.add_extension", ["phoenix"])
```

--------------------------------

### Use Module Attributes for Documentation in Elixir

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Store documentation strings in module attributes for better organization and reusability within your Elixir modules. These attributes can be used throughout your Igniter tasks.

```elixir
defmodule Mix.Tasks.YourLibrary.Install do
  @manual_lead_in """
  This guide walks you through manually installing YourLibrary.
  """

  @dependency_setup """
  Install required dependencies and configure them for your project.
  """

  @formatter_setup """
  Configure code formatting for your DSL.
  """

  # Use these throughout your igniter/1 function
end
```

--------------------------------

### Igniter.Scribe.patch/2

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Captures and documents file changes made by a callback function, generating diffs or full content for new files.

```APIDOC
## `patch/2`

Captures changes made by a function and includes them in the documentation as code diffs.

```elixir
Igniter.Scribe.patch(igniter, callback)
```

**Parameters:**
- `igniter` - The Igniter struct
- `callback` - A function that receives the igniter and returns a modified igniter

The patch function will:
- Compare the before and after state of files
- Generate diffs for modified files
- Show creation of new files with full content
- Automatically format the output with appropriate syntax highlighting

**Example:**

```elixir
igniter
|> Igniter.Scribe.patch(fn igniter ->
  igniter
  |> Igniter.Project.Config.configure("config.exs", :your_library, [:option], true)
  |> Igniter.Project.Module.create_module(YourApp.SomeModule, """
defmodule YourApp.SomeModule do
  # Module content here
end
""")
end)
```
```

--------------------------------

### Add Igniter to Elixir Project Dependencies

Source: https://github.com/ash-project/igniter/blob/main/README.md

Add Igniter to your project's dependencies in `mix.exs` for development and testing. This allows you to use Igniter's mix tasks within your project.

```elixir
 {:igniter, "~> 0.6", only: [:dev, :test]}
```

--------------------------------

### Capture File Changes with Patch

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

The `Igniter.Scribe.patch/2` function captures changes made by a callback function and includes them as code diffs in the documentation. It shows diffs for modified files and the full content of new files.

```elixir
igniter
|> Igniter.Scribe.patch(fn igniter ->
  igniter
  |> Igniter.Project.Config.configure("config.exs", :your_library, [:option], true)
  |> Igniter.Project.Module.create_module(YourApp.SomeModule, """
defmodule YourApp.SomeModule do
  # Module content here
end
""")
end)
```

--------------------------------

### Group Related Changes in Igniter

Source: https://github.com/ash-project/igniter/blob/main/documentation/documenting-tasks.md

Use Igniter.Scribe.section to group logically related changes within a task. This helps in organizing the documentation and the underlying code.

```elixir
igniter
|> Igniter.Scribe.section("Configure Application", @config_explanation, fn igniter ->
  igniter
  |> Igniter.Scribe.patch(&configure_main_settings/1)
  |> Igniter.Scribe.patch(&configure_optional_settings/1)
  |> Igniter.Scribe.patch(&setup_environment_configs/1)
end)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.