diff --git a/documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md b/documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md new file mode 100644 index 0000000..13fee08 --- /dev/null +++ b/documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md @@ -0,0 +1,189 @@ + +# Diffo.Provider.Instance.Extension + +DSL Extension customising an Instance + + +## specification +Defines the Instance Specification + + + +### Examples +``` +specification do + id "da9b207a-26c3-451d-8abd-0640c6349979" + name "DSL Access Service" + type :serviceSpecification + major_version 1 + description "An access network service connecting a subscriber premises to an access NNI via DSL" + category "Network Service" +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`id`](#specification-id){: #specification-id .spark-required} | `String.t` | | The id of the specification, a uuid4 the same in all environments, unique for name and major_version. | +| [`name`](#specification-name){: #specification-name .spark-required} | `String.t` | | The name of the specification, unique to a service but common for all versions. | +| [`type`](#specification-type){: #specification-type } | `atom` | `:serviceSpecification` | The type of the specification. | +| [`major_version`](#specification-major_version){: #specification-major_version } | `integer` | `1` | The major_version of the specification. | +| [`description`](#specification-description){: #specification-description } | `String.t` | | A generic description of the specified service or resource. | +| [`category`](#specification-category){: #specification-category } | `String.t` | | The category the specified service or resource belongs to. | + + + + + + +## features +Configuration for Instance Features + +### Nested DSLs + * [feature](#features-feature) + * characteristic + + +### Examples +``` +features do + feature :dynamic_line_management do + is_enabled? true + characteristics do + characteristic :constraints, Diffo.Access.Constraints + end + end +end + +``` + + + + +### features.feature +```elixir +feature name +``` + + +Adds a Feature + +### Nested DSLs + * [characteristic](#features-feature-characteristic) + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#features-feature-name){: #features-feature-name .spark-required} | `atom` | | The name of the feature, an atom | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`is_enabled?`](#features-feature-is_enabled?){: #features-feature-is_enabled? } | `boolean` | | Whether the feature is enabled by default, defaults true | + + +### features.feature.characteristic +```elixir +characteristic name, value_type +``` + + +Adds a Characteristic + + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#features-feature-characteristic-name){: #features-feature-characteristic-name .spark-required} | `atom` | | The name of the characteristic, an atom | +| [`value_type`](#features-feature-characteristic-value_type){: #features-feature-characteristic-value_type } | `atom` | | The optional type of the characteristic's value, an atom, may be a module name such as an Ash.TypedStruct | + + + + + + +### Introspection + +Target: `Diffo.Provider.Instance.Characteristic` + + + + +### Introspection + +Target: `Diffo.Provider.Instance.Feature` + + + + +## characteristics +List of Instance Characteristics + +### Nested DSLs + * [characteristic](#characteristics-characteristic) + + +### Examples +``` +characteristics do + characteristic :dslam, Diffo.Access.Dslam + characteristic :aggregate_interface, Diffo.Access.AggregateInterface + characteristic :circuit, Diffo.Access.Circuit + characteristic :line, Diffo.Access.Line +end + +``` + + + + +### characteristics.characteristic +```elixir +characteristic name, value_type +``` + + +Adds a Characteristic + + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#characteristics-characteristic-name){: #characteristics-characteristic-name .spark-required} | `atom` | | The name of the characteristic, an atom | +| [`value_type`](#characteristics-characteristic-value_type){: #characteristics-characteristic-value_type } | `atom` | | The optional type of the characteristic's value, an atom, may be a module name such as an Ash.TypedStruct | + + + + + + +### Introspection + +Target: `Diffo.Provider.Instance.Characteristic` + + + + + + diff --git a/documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md.license b/documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md.license new file mode 100644 index 0000000..40c9cb0 --- /dev/null +++ b/documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2025 diffo contributors + +SPDX-License-Identifier: MIT \ No newline at end of file diff --git a/lib/diffo/access/resources/cable.ex b/lib/diffo/access/resources/cable.ex index 4c42582..1d91673 100644 --- a/lib/diffo/access/resources/cable.ex +++ b/lib/diffo/access/resources/cable.ex @@ -16,9 +16,10 @@ defmodule Diffo.Access.Cable do alias Diffo.Provider.Instance.Characteristic alias Diffo.Provider.Instance.Place alias Diffo.Provider.Instance.Party + alias Diffo.Provider.Assigner + alias Diffo.Provider.Assignment + alias Diffo.Access - alias Diffo.Access.Assigner - alias Diffo.Access.Assignment use Ash.Resource, fragments: [BaseInstance], @@ -39,7 +40,7 @@ defmodule Diffo.Access.Cable do characteristics do characteristic :cable, Diffo.Access.CableValue - characteristic :pairs, Diffo.Access.AssignableValue + characteristic :pairs, Diffo.Provider.AssignableValue end actions do diff --git a/lib/diffo/access/resources/card.ex b/lib/diffo/access/resources/card.ex index 2e24924..b6d3b33 100644 --- a/lib/diffo/access/resources/card.ex +++ b/lib/diffo/access/resources/card.ex @@ -16,9 +16,10 @@ defmodule Diffo.Access.Card do alias Diffo.Provider.Instance.Characteristic alias Diffo.Provider.Instance.Place alias Diffo.Provider.Instance.Party + alias Diffo.Provider.Assigner + alias Diffo.Provider.Assignment + alias Diffo.Access - alias Diffo.Access.Assigner - alias Diffo.Access.Assignment use Ash.Resource, fragments: [BaseInstance], @@ -39,7 +40,7 @@ defmodule Diffo.Access.Card do characteristics do characteristic :card, Diffo.Access.CardValue - characteristic :ports, Diffo.Access.AssignableValue + characteristic :ports, Diffo.Provider.AssignableValue end actions do diff --git a/lib/diffo/access/resources/shelf.ex b/lib/diffo/access/resources/shelf.ex index eb08bbd..33c40c7 100644 --- a/lib/diffo/access/resources/shelf.ex +++ b/lib/diffo/access/resources/shelf.ex @@ -16,9 +16,10 @@ defmodule Diffo.Access.Shelf do alias Diffo.Provider.Instance.Characteristic alias Diffo.Provider.Instance.Place alias Diffo.Provider.Instance.Party + alias Diffo.Provider.Assigner + alias Diffo.Provider.Assignment + alias Diffo.Access - alias Diffo.Access.Assigner - alias Diffo.Access.Assignment use Ash.Resource, fragments: [BaseInstance], @@ -39,7 +40,7 @@ defmodule Diffo.Access.Shelf do characteristics do characteristic :shelf, Diffo.Access.ShelfValue - characteristic :slots, Diffo.Access.AssignableValue + characteristic :slots, Diffo.Provider.AssignableValue end actions do diff --git a/lib/diffo/access/assigner/assignable_value.ex b/lib/diffo/provider/assigner/assignable_value.ex similarity index 96% rename from lib/diffo/access/assigner/assignable_value.ex rename to lib/diffo/provider/assigner/assignable_value.ex index 9120594..4358856 100644 --- a/lib/diffo/access/assigner/assignable_value.ex +++ b/lib/diffo/provider/assigner/assignable_value.ex @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: MIT -defmodule Diffo.Access.AssignableValue do +defmodule Diffo.Provider.AssignableValue do @moduledoc """ Diffo - TMF Service and Resource Management with a difference diff --git a/lib/diffo/access/assigner/assigner.ex b/lib/diffo/provider/assigner/assigner.ex similarity index 95% rename from lib/diffo/access/assigner/assigner.ex rename to lib/diffo/provider/assigner/assigner.ex index 447b293..ed4d415 100644 --- a/lib/diffo/access/assigner/assigner.ex +++ b/lib/diffo/provider/assigner/assigner.ex @@ -2,14 +2,14 @@ # # SPDX-License-Identifier: MIT -defmodule Diffo.Access.Assigner do +defmodule Diffo.Provider.Assigner do @moduledoc """ Diffo - TMF Service and Resource Management with a difference Assigner - Helper to perform Assignment maintaining AssignableValue """ - alias Diffo.Access.AssignableValue + alias Diffo.Provider.AssignableValue @doc """ Assign a thing using the instance changeset assignment @@ -101,7 +101,10 @@ defmodule Diffo.Access.Assigner do if characteristic do assignment = - struct(Diffo.Access.Assignment, %{id: characteristic.value, instance_id: target_id}) + struct(Diffo.Provider.Assignment, %{ + id: characteristic.value, + instance_id: target_id + }) [assignment | acc] else @@ -112,7 +115,7 @@ defmodule Diffo.Access.Assigner do acc end end) - |> Enum.sort(Diffo.Access.Assignment) + |> Enum.sort(Diffo.Provider.Assignment) end defp next(instance, things, thing) diff --git a/lib/diffo/access/assigner/assignment.ex b/lib/diffo/provider/assigner/assignment.ex similarity index 96% rename from lib/diffo/access/assigner/assignment.ex rename to lib/diffo/provider/assigner/assignment.ex index 6ff6859..131f041 100644 --- a/lib/diffo/access/assigner/assignment.ex +++ b/lib/diffo/provider/assigner/assignment.ex @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: MIT -defmodule Diffo.Access.Assignment do +defmodule Diffo.Provider.Assignment do @moduledoc """ Diffo - TMF Service and Resource Management with a difference diff --git a/lib/diffo/provider/components/instance/extension/characteristic.ex b/lib/diffo/provider/components/instance/extension/characteristic.ex index 47f01e0..fd93018 100644 --- a/lib/diffo/provider/components/instance/extension/characteristic.ex +++ b/lib/diffo/provider/components/instance/extension/characteristic.ex @@ -18,7 +18,7 @@ defmodule Diffo.Provider.Instance.Characteristic do @doc """ Struct for a Characteristic """ - defstruct [:name, :value_type] + defstruct [:name, :value_type, __spark_metadata__: nil] @doc """ Sets the Extended Instances characteristics argument in the changeset, creating the characteristics diff --git a/lib/diffo/provider/components/instance/extension/feature.ex b/lib/diffo/provider/components/instance/extension/feature.ex index 04b5e15..f8d8a9f 100644 --- a/lib/diffo/provider/components/instance/extension/feature.ex +++ b/lib/diffo/provider/components/instance/extension/feature.ex @@ -18,7 +18,7 @@ defmodule Diffo.Provider.Instance.Feature do @doc """ Struct for a Feature """ - defstruct [:name, :is_enabled?, :characteristics] + defstruct [:name, :is_enabled?, :characteristics, __spark_metadata__: nil] @doc """ Sets the Extended Instances features argument in the changeset, creating the features and feature characteristics diff --git a/mix.exs b/mix.exs index f2786fa..1220213 100644 --- a/mix.exs +++ b/mix.exs @@ -20,12 +20,15 @@ defmodule Diffo.MixProject do elixir: "~> 1.18", start_permanent: Mix.env() == :prod, package: package(), - deps: deps(), - aliases: aliases(), - elixirc_paths: elixirc_paths(Mix.env()), + # ex_doc source_url: "https://github.com/diffo-dev/diffo/", homepage_url: "http://diffo.dev/diffo/", - docs: docs() + docs: [main: "readme", extras: ["README.md"]], + elixirc_paths: elixirc_paths(Mix.env()), + # hex.pm stuff + deps: deps(), + docs: &docs/0, + aliases: aliases() ] end @@ -64,7 +67,11 @@ defmodule Diffo.MixProject do logo: "logos/diffo.jpg", extras: [ "README.md": [title: "Guide"], - "LICENSES/MIT.md": [title: "License"] + "LICENSES/MIT.md": [title: "License"], + "documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md": [ + title: "DSL: Diffo.Provider.Instance.Extension", + search_data: Spark.Docs.search_data_for(Diffo.Provider.Instance.Extension) + ] ] ] end @@ -97,7 +104,20 @@ defmodule Diffo.MixProject do end defp aliases() do - [test: ["ash.setup --quiet", "test"], setup: "ash.setup"] + [ + test: ["ash.setup --quiet", "test"], + setup: "ash.setup", + docs: [ + "spark.cheat_sheets", + "docs", + "spark.replace_doc_links" + ], + "spark.cheat_sheets": "spark.cheat_sheets --extensions Diffo.Provider.Instance.Extension", + "spark.formatter": [ + "spark.formatter --extensions Diffo.Provider.Instance.Extension", + "format .formatter.exs" + ] + ] end defp elixirc_paths(:test), do: elixirc_paths(:dev) ++ ["test/support"] diff --git a/test/access/cable_test.exs b/test/access/cable_test.exs index 7e2ff2b..5cc5f07 100644 --- a/test/access/cable_test.exs +++ b/test/access/cable_test.exs @@ -7,9 +7,9 @@ defmodule Diffo.Access.CableTest do use ExUnit.Case alias Diffo.Provider.Specification alias Diffo.Provider.Characteristic + alias Diffo.Provider.Assignment alias Diffo.Access alias Diffo.Access.Cable - alias Diffo.Access.Assignment alias Diffo.Access.IntegerUnit alias Diffo.Test.Characteristics diff --git a/test/access/card_test.exs b/test/access/card_test.exs index 5f6e4e1..f1c555c 100644 --- a/test/access/card_test.exs +++ b/test/access/card_test.exs @@ -9,7 +9,7 @@ defmodule Diffo.Access.CardTest do alias Diffo.Provider.Characteristic alias Diffo.Access alias Diffo.Access.Card - alias Diffo.Access.Assignment + alias Diffo.Provider.Assignment alias Diffo.Test.Characteristics setup_all do diff --git a/test/access/path_test.exs b/test/access/path_test.exs index 0b885ba..c2afc34 100644 --- a/test/access/path_test.exs +++ b/test/access/path_test.exs @@ -11,9 +11,9 @@ defmodule Diffo.Access.PathTest do alias Diffo.Provider.Instance.Place alias Diffo.Provider.Instance.Party alias Diffo.Provider.Instance.Relationship + alias Diffo.Provider.Assignment alias Diffo.Access alias Diffo.Access.Path - alias Diffo.Access.Assignment setup_all do AshNeo4j.BoltxHelper.start() diff --git a/test/access/shelf_test.exs b/test/access/shelf_test.exs index c84c3e6..d17dbda 100644 --- a/test/access/shelf_test.exs +++ b/test/access/shelf_test.exs @@ -11,9 +11,9 @@ defmodule Diffo.Access.ShelfTest do alias Diffo.Provider.Instance.Place alias Diffo.Provider.Instance.Party alias Diffo.Provider.Instance.Relationship + alias Diffo.Provider.Assignment alias Diffo.Access alias Diffo.Access.Shelf - alias Diffo.Access.Assignment alias Diffo.Test.Characteristics setup_all do