# `Spark.Builder.Section`
[🔗](https://github.com/ash-project/spark/blob/v2.7.0/lib/spark/builder/section.ex#L5)

Builder for constructing `Spark.Dsl.Section` structs.

This module provides an options-based API for creating DSL section
definitions programmatically. Sections organize related configurations
and can contain entities, nested sections, and schema options.

## Examples

    alias Spark.Builder.{Section, Entity}

    section = Section.new(:attributes,
      describe: "Configure resource attributes",
      schema: [
        primary_key: [type: :boolean, default: true, doc: "Include primary key"]
      ],
      entities: [attribute_entity]
    )
    |> Section.build!()

## Nested Sections

Sections can contain nested sections via the `:sections` option:

    Section.new(:resource,
      sections: [
        Section.new(:attributes,
          entities: [attribute_entity]
        )
        |> Section.build!()
      ]
    )
    |> Section.build!()

## Accepted Options

  - `:schema` - Schema for section-level options
  - `:entities` - List of entities in this section
  - `:sections` - List of nested sections
  - `:top_level?` - Whether the section can be used at module level without a `do` block
  - `:patchable?` - Whether other extensions can add entities via patches
  - `:auto_set_fields` - Fields automatically set on entities in this section
  - `:after_define` - Callback to run after the section is defined as `{module, function}`
  - `:describe` - Description for documentation
  - `:examples` - List of example strings
  - `:snippet` - IDE autocomplete snippet
  - `:links` - Documentation links
  - `:deprecations` - Deprecation warnings for specific options
  - `:docs` - Additional documentation
  - `:imports` - Modules to import in the section's DSL scope
  - `:modules` - Schema fields containing module references
  - `:no_depend_modules` - Module fields that should not create dependencies

# `t`
*since 2.5.0* 

```elixir
@type t() :: %Spark.Builder.Section{
  after_define: {module(), atom()} | nil,
  auto_set_fields: keyword(),
  deprecations: keyword(String.t()),
  describe: String.t(),
  docs: String.t(),
  entities: [Spark.Dsl.Entity.t()],
  examples: [String.t()],
  imports: [module()],
  links: keyword([String.t()]) | nil,
  modules: [atom()],
  name: atom() | nil,
  no_depend_modules: [atom()],
  patchable?: boolean(),
  schema: Spark.Options.schema(),
  sections: [Spark.Dsl.Section.t()],
  singleton_entity_keys: term(),
  snippet: String.t(),
  top_level?: boolean()
}
```

# `build`
*since 2.5.0* 

```elixir
@spec build(t()) :: {:ok, Spark.Dsl.Section.t()} | {:error, String.t()}
```

Builds the `%Spark.Dsl.Section{}` struct.

Returns `{:ok, section}` on success or `{:error, reason}` on validation failure.

## Examples

    {:ok, section} = Section.new(:fields,
      entities: [field_entity]
    )
    |> Section.build()

# `build!`
*since 2.5.0* 

```elixir
@spec build!(t()) :: Spark.Dsl.Section.t()
```

Builds the `%Spark.Dsl.Section{}` struct, raising on validation errors.

## Examples

    section = Section.new(:fields,
      entities: [field_entity]
    )
    |> Section.build!()

# `new`
*since 2.5.0* 

```elixir
@spec new(
  atom(),
  keyword()
) :: t()
```

Creates a new section builder with the given name and options.

## Parameters

  - `name` - The atom name for the DSL section (e.g., `:attributes`)
  - `opts` - Options to configure the section (see module docs for accepted options)

## Examples

    iex> Section.new(:attributes)
    %Spark.Builder.Section{name: :attributes}

    iex> Section.new(:attributes,
    ...>   describe: "Resource attributes",
    ...>   top_level?: true
    ...> )
    %Spark.Builder.Section{name: :attributes, describe: "Resource attributes", top_level?: true}

---

*Consult [api-reference.md](api-reference.md) for complete listing*