35 improve extension

documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md

@@ -0,0 +1,189 @@
+<!--
+
+
+This file was generated by Spark. Do not edit it by hand.
+-->
+# 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`
+
+
+
+
+
+<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>

documentation/dsls/DSL-Diffo.Provider.Instance.Extension.md.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+
+SPDX-License-Identifier: MIT

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

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

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

lib/diffo/access/assigner/assignable_value.ex → 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
 

lib/diffo/access/assigner/assigner.ex → 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)

lib/diffo/access/assigner/assignment.ex → 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
 

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

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

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"]