docs: move around some docs

documentation/home.md

@@ -45,6 +45,7 @@ Welcome to the Ash Framework documentation! Here you will find everything you ne
 - [Update Actions](documentation/topics/actions/update-actions.md)
 - [Destroy Actions](documentation/topics/actions/destroy-actions.md)
 - [Generic Actions](documentation/topics/actions/generic-actions.md)
+- [Manual Actions](documentation/topics/actions/manual-actions.md)
 
 ### Security
 

documentation/topics/actions/manual-actions.md

@@ -6,7 +6,7 @@ Manual actions are a way to implement an action in a fully custom way. This can
 
 ## Manual Creates/Updates/Destroy
 
-For manual create, update and destroy actions, a module is passed that uses one of the provided modules (Ash.Resource.ManualCreate, Ash.Resource.ManualUpdate and Ash.Resource.ManualDestroy).
+For manual create, update and destroy actions, a module is passed that uses one of the following (`Ash.Resource.ManualCreate`, `Ash.Resource.ManualUpdate` and `Ash.Resource.ManualDestroy`).
 
 For example:
 

documentation/topics/resources/embedded-resources.md

@@ -1,8 +1,6 @@
 # Embedded Resources
 
-Embedded resources function very similarly to [embedded schemas in Ecto](https://hexdocs.pm/ecto/Ecto.Schema.html).
-The primary difference is the same as the primary difference between Ecto schemas and Ash resources: the full lifecycle
-of the resource is managed by its configuration. For example, you can add validations, calculations, and even authorization policies to an embedded resource. Here is an example of a simple embedded resource:
+Embedded resources are stored as maps in attributes of other resources. They are great for storing structured data, and support a whole range of useful features that resources support. For example, you can have calculations, validations, policies and even relationships on embedded resources.Here is an example of a simple embedded resource:
 
 ```elixir
 defmodule MyApp.Profile do
@@ -10,13 +8,14 @@ defmodule MyApp.Profile do
     data_layer: :embedded # Use the atom `:embedded` as the data layer.
 
   attributes do
-    attribute :first_name, :string
-    attribute :last_name, :string
+    attribute :first_name, :string, public?: true
+    attribute :last_name, :string, public?: true
   end
 end
 ```
 
-Embedded resources cannot have relationships or aggregates.
+> ### embedded resources can't do everything {: .info}
+> Embedded resources cannot have aggregates, or expression calculations that rely on data-layer-specific capabilities. It typically depends on the data layer what embedded resources can/can't do.
 
 ## Adding embedded resource attributes
 
@@ -29,13 +28,13 @@ defmodule MyApp.User do
   attributes do
     ...
 
-    attribute :profile, MyApp.Profile
-    attribute :profiles, {:array, MyApp.Profile} # You can also have an array of embeds
+    attribute :profile, MyApp.Profile, public?: true
+    attribute :profiles, {:array, MyApp.Profile}, public?: true # You can also have an array of embeds
   end
 end
 ```
 
-## Nil values
+## Handling nil values
 
 By default, all fields on an embedded resource will be included in the data layer, including keys with nil values. To prevent this, add the `embed_nil_values?` option to `use Ash.Resource`. For example:
 
@@ -70,8 +69,8 @@ defmodule MyApp.Profile do
     data_layer: :embedded # Use the atom `:embedded` as the data layer.
 
   attributes do
-    attribute :first_name, :string
-    attribute :last_name, :string
+    attribute :first_name, :string, public?: true
+    attribute :last_name, :string, public?: true
   end
 
   validations do
@@ -91,8 +90,8 @@ defmodule MyApp.Profile do
     data_layer: :embedded # Use the atom `:embedded` as the data layer.
 
   attributes do
-    attribute :first_name, :string
-    attribute :last_name, :string
+    attribute :first_name, :string, public?: true
+    attribute :last_name, :string, public?: true
   end
 
   calculations do
@@ -106,6 +105,7 @@ defmodule MyApp.User do
 
   attributes do
     attribute :profile, MyApp.Profile do
+      public? true
       constraints [load: [:full_name]]
     end
   end
@@ -139,8 +139,8 @@ defmodule MyApp.Tag do
 
   attributes do
     uuid_primary_key :id
-    attribute :name, :string
-    attribute :counter, :integer
+    attribute :name, :string, public?: true
+    attribute :counter, :integer, public?: true
   end
 
   validations do

mix.exs

@@ -47,12 +47,14 @@ defmodule Ash.MixProject do
         "documentation/topics/about_ash/design-principles.md",
         "documentation/topics/about_ash/contributing-to-ash.md",
         "documentation/topics/resources/attributes.md",
+        "documentation/topics/resources/embedded-resources.md",
         "documentation/topics/actions/actions.md",
         "documentation/topics/actions/read-actions.md",
         "documentation/topics/actions/create-actions.md",
         "documentation/topics/actions/update-actions.md",
         "documentation/topics/actions/destroy-actions.md",
         "documentation/topics/actions/generic-actions.md",
+        "documentation/topics/actions/manual-actions.md",
         "documentation/topics/development/development-utilities.md",
         "documentation/topics/development/upgrading-to-3.0.md",
         "documentation/topics/security/actors-and-authorization.md",
@@ -67,13 +69,11 @@ defmodule Ash.MixProject do
         "documentation/topics/resources/aggregates.md",
         "documentation/topics/resources/calculations.md",
         "documentation/topics/code-interface.md",
-        "documentation/topics/embedded-resources.md",
         "documentation/topics/extending-resources.md",
         "documentation/topics/expressions.md",
         "documentation/topics/reference/glossary.md",
         "documentation/topics/identities.md",
         "documentation/topics/managing-relationships.md",
-        "documentation/topics/manual-actions.md",
         "documentation/topics/monitoring.md",
         "documentation/topics/multitenancy.md",
         "documentation/topics/notifiers.md",
@@ -103,6 +103,7 @@ defmodule Ash.MixProject do
           "documentation/topics/resources/attributes.md",
           "documentation/topics/resources/calculations.md",
           "documentation/topics/resources/aggregates.md"
+          "documentation/topics/resources/embedded-resources.md",
         ],
         Actions: [
           "documentation/topics/actions/actions.md",
@@ -110,7 +111,8 @@ defmodule Ash.MixProject do
           "documentation/topics/actions/create-actions.md",
           "documentation/topics/actions/update-actions.md",
           "documentation/topics/actions/destroy-actions.md",
-          "documentation/topics/actions/generic-actions.md"
+          "documentation/topics/actions/generic-actions.md",
+          "documentation/topics/actions/manual-actions.md",
         ],
         Security: [
           "documentation/topics/security/actors-and-authorization.md",
@@ -148,12 +150,10 @@ defmodule Ash.MixProject do
           "documentation/how_to/use-without-data-layers.md",
           "documentation/how_to/validate-changes.md",
           "documentation/topics/code-interface.md",
-          "documentation/topics/embedded-resources.md",
           "documentation/topics/extending-resources.md",
           "documentation/topics/expressions.md",
           "documentation/topics/identities.md",
           "documentation/topics/managing-relationships.md",
-          "documentation/topics/manual-actions.md",
           "documentation/topics/monitoring.md",
           "documentation/topics/multitenancy.md",
           "documentation/topics/notifiers.md",