diff --git a/documentation/home.md b/documentation/home.md index 58df8d05..b974f8a1 100644 --- a/documentation/home.md +++ b/documentation/home.md @@ -4,7 +4,7 @@ Welcome to the Ash Framework documentation! Here you will find everything you ne ## Dive In -- [What is Ash?](documentation/how_to/what-is-ash.md) +- [What is Ash?](documentation/topics/about_ash/what-is-ash.md) - [Get Started](documentation/tutorials/get-started.md) ## About the Documentation @@ -31,11 +31,13 @@ Welcome to the Ash Framework documentation! Here you will find everything you ne ## Topics +- [Glossary](documentation/topics/glossary.md) + ### About Ash -- [What is Ash?](documentation/topics/what-is-ash.md) -- [Our Design Principles](documentation/topics/design-principles.md) -- [Contributing to Ash](documentation/topics/contributing-to-ash.md) +- [What is Ash?](documentation/topics/about_ash/what-is-ash.md) +- [Our Design Principles](documentation/topics/about_ash/design-principles.md) +- [Contributing to Ash](documentation/topics/about_ash/contributing-to-ash.md) --- @@ -85,5 +87,3 @@ The Ash ecosystem consists of numerous packages, all of which have their own doc ### Testing - [Smokestack](https://hexdocs.pm/smokestack) | Declarative test factories for Ash resources - ---- diff --git a/documentation/topics/contributing-to-ash.md b/documentation/topics/about_ash/contributing-to-ash.md similarity index 100% rename from documentation/topics/contributing-to-ash.md rename to documentation/topics/about_ash/contributing-to-ash.md diff --git a/documentation/topics/design-principles.md b/documentation/topics/about_ash/design-principles.md similarity index 100% rename from documentation/topics/design-principles.md rename to documentation/topics/about_ash/design-principles.md diff --git a/documentation/topics/what-is-ash.md b/documentation/topics/about_ash/what-is-ash.md similarity index 100% rename from documentation/topics/what-is-ash.md rename to documentation/topics/about_ash/what-is-ash.md diff --git a/documentation/topics/domains.md b/documentation/topics/domains.md new file mode 100644 index 00000000..e69de29b diff --git a/documentation/topics/glossary.md b/documentation/topics/glossary.md index 1aad16f1..594f5839 100644 --- a/documentation/topics/glossary.md +++ b/documentation/topics/glossary.md @@ -9,17 +9,17 @@ An action describes an operation that can be performed for a given resource; it - BlogPost._publish_ - Article._search_ -Ash supports four different types of actions - `create`, `read`, `update` and `destroy` (collectively often abbreviated as CRUD). A resource can define multiple actions per action type, eg. a _publish_ action would be considered an `update` because it is updating an existing instance of a resource. Actions are much more flexible than simple CRUD, but these four action types serve as templates for anything you might want to do. +Ash supports five different types of actions. `create`, `read`, `update` and `destroy` (collectively often abbreviated as CRUD), and `action`, referring to a generic action with a custom return type. A resource can define multiple actions per action type, eg. a _publish_ action would be considered an `update` because it is updating an existing instance of a resource. Actions are much more flexible than simple CRUD, but these five action types serve as templates for anything you might want to do. -See the [Actions guide](/documentation/topics/actions.md) for more information. +See the [Actions guide](/documentation/topics/actions.md) for more. ## Actor -The entity that performs an action. Most actions are run on direct user request, eg. if a user presses a Create button on a page then the actor is the user; but an actor might also be an organization, a group, or the system itself. +The entity that performs an action. Most actions are run on direct user request, eg. if a user presses a Create button on a page then the actor is the user; but an actor might also be an organization, a group, or even a device. -Actors are referenced during authorization - ensuring that the actor is allowed to perform an action, before it takes place. The actor can also be used within actions, to record which entity performed the action. +Actors can be used in a number of places, from modifying the behavior of an action to auditing who did what in your system. They are most prominent, however, when writing [policies](#policy). -See the [Security guide](/documentation/topics/security.md#actors) for more information. +See the [Security guide](/documentation/topics/security.md#actors) for more. ## Aggregate @@ -27,59 +27,60 @@ An aggregate is a special type of field for a resource, one that summarizes rela If a Project resource has_many Ticket resources, an example of an aggregate on the Project might be to count the tickets associated to each project. -See the [Aggregates guide](/documentation/topics/aggregates.md) for more information. +See the [Aggregates guide](/documentation/topics/aggregates.md) for more. ## Domain A method of broadly separating resources into different [domains](), A.K.A [bounded contexts](https://martinfowler.com/bliki/BoundedContext.html). -See `d:Ash.Domain` for more information. +See the [Domains guide](/documentation/topics/domains.md) for more. ## Attribute -A piece of data belonging to a resource. The most basic building block; an attribute has a type and a value and is stored within the context of a domain model. +A piece of data belonging to a resource. The most basic building block; an attribute has a type and a value. For resources backed by a data layer, they typically represent a column in a database table, or a key in an object store, for example. -See `d:Ash.Resource.Dsl.attributes` for more information. +See the [Attributes guide](/documentation/topics/attributes.md) for more. ## Calculation -A calculation is a special type of field for a resource, one that is not directly stored in the data layer but generated on-demand when specifically requested as part of a query. Typically it will derive from other information on the record, but it may come from some other data source entirely. +A calculation is a special type of field for a resource, one that is not directly stored in the data layer but generated on-demand. Typically it will derive from other information on the record, but it may come from some other data source entirely. -See the [Calculations guide](/documentation/topics/calculations.md) for more information. +See the [Calculations guide](/documentation/topics/calculations.md) for more. ## Changeset Changesets encapsulate data changes made while creating or updating an instance of a resource. Similarly to [Ecto changesets](https://hexdocs.pm/ecto/Ecto.Changeset.html), they include data validations but they also have their own callback hook lifecycle. -See `Ash.Changeset` for more information. +See `Ash.Changeset` for more. ## Extension A packaged bundle of code that can be included in a resource to provide additional functionality. Built-in functionality such as the resource DSL itself is provided by an extension, and libraries like AshPostgres and AshAdmin also provide extensions that you can add to your resources with just one line of code. -See [Extending Resources](/documentation/topics/extending-resources.md) for more information. +See [Extending Resources](/documentation/topics/extending-resources.md) for more. ## Filter -The tools and functions used to reduce the amount of data returned when running queries on the data layer. This may look like: +Filters are applied to queries to limit the data returned. They can also be applied to changesets, to ensure only data matching a certain condition is updated. For example: - Fetching Articles that include a certain search term in the title - Fetching Posts created by a specific user - Fetching Tickets updated in the last week +- Updating a record only if it's version matches your in memory version (optimistic locking) -See `Ash.Filter` for more information. +See `Ash.Filter` for more. ## Identity -A way to uniquely identify an instance of a resource. A primary key is an example of an identity that is automatically generated; you can manually add others such as a user's email address, or a URL slug for a post. If using AshPostgres, constraints will be created to enforce identities at the database level. +A way to uniquely identify an instance of a resource. A primary key is an example of an identity that is automatically generated; you can manually add others such as a user's email address, or a URL slug for a post. If using AshPostgres, constraints will be created by the migration generator to enforce identities at the database level. -See the [Identities guide](/documentation/topics/identities.md) for more information. +See the [Identities guide](/documentation/topics/identities.md) for more. ## Notifier -Notifiers are modules that insert callbacks into the lifecycle of a resource action, to be _notified_ when actions take place. When connected to a resource they are invoked after every action, but via pattern matching on the notification received, they can be made very granular. +Notifiers are modules that are called for each action that occurs on a resource (except generic actions). They are called at the end of transactions, meaning that if a notifier is called, it is guaranteed that the action they pertain to has completed successfully. -See the [Notifiers guide](/documentation/topics/notifiers.md) for more information. +See the [Notifiers guide](/documentation/topics/notifiers.md) for more. ## Policy @@ -88,25 +89,23 @@ A set of rules defining who is authorized to perform specific actions on a resou - Forbidding anyone other than the user who wrote a blog post, from editing it - Allowing only admins to update site-wide settings -See the [Policies guide](/documentation/topics/policies.md) for more information. +See the [Policies guide](/documentation/topics/policies.md) for more. ## Query The tools and functions used for reading and filtering stored data, from the data layer. -See `Ash.Query` for more information. +See `Ash.Query` for more. ## Relationship -Relationships (also known as _associations_) are named links between resources, that define how they relate to each other. Relationships can be used to signify ownership of a record, membership of a group, or can be used in filtering and querying data. +Relationships are named links between resources, that define how they relate to each other. Relationships can be used to signify ownership of a record, membership of a group, or can be used in filtering and querying data. -See the [Relationships guide](/documentation/topics/relationships.md) for more information. +See the [Relationships guide](/documentation/topics/relationships.md) for more. ## Resource -The central concept in Ash, a resource is a domain model object in your system, the nouns that your app revolves around. Resources contain definitions of the data they hold in the form of attributes, but also define [actions](#action) that can be taken on that data and [actors](#actor) that are allowed to run them. - -It is not a strict requirement that resources contain data - they can be used purely to create a standard interface for performing tasks - but in practice, most resources will be used to manage data. +The central concept in Ash, a resource can be used to model all kinds of things. Most often, they will map to a data store, and represent things like rows of a database table. However, they can also be backed by external data sources, be used for validating data with no persistence at all, or even be simple containers for generic actions, completely stateless. See the [Resource DSL docs](dsl-ash-resource.html) for DSL documentation. @@ -114,4 +113,4 @@ See the [Resource DSL docs](dsl-ash-resource.html) for DSL documentation. Multitenancy is the siloing of your app's data into discrete non-overlapping groups, typically by customer or organization (the tenant). Ash supports multitenancy both at the code level and the data layer level (depending on the data layer; for example, AshPostgres uses schemas to fully separate data per tenant.) -See the [Multitenancy guide](/documentation/topics/multitenancy.md) for more information. +See the [Multitenancy guide](/documentation/topics/multitenancy.md) for more. diff --git a/mix.exs b/mix.exs index ae593bce..22f51aec 100644 --- a/mix.exs +++ b/mix.exs @@ -43,9 +43,9 @@ defmodule Ash.MixProject do extras: [ {"documentation/home.md", title: "Home"}, "documentation/tutorials/get-started.md", - "documentation/topics/what-is-ash.md", - "documentation/topics/design-principles.md", - "documentation/topics/contributing-to-ash.md", + "documentation/topics/about_ash/what-is-ash.md", + "documentation/topics/about_ash/design-principles.md", + "documentation/topics/about_ash/contributing-to-ash.md", "CHANGELOG.md", "documentation/how_to/define-idiomatic-actions.md", "documentation/how_to/defining-manual-relationships.md", @@ -84,7 +84,15 @@ defmodule Ash.MixProject do "documentation/topics/store-context-in-process.md", "documentation/topics/testing.md", "documentation/topics/timeouts.md", - "documentation/topics/validations.md" + "documentation/topics/validations.md", + "documentation/dsls/DSL:-Ash.Resource.md", + "documentation/dsls/DSL:-Ash.Domain.md", + "documentation/dsls/DSL:-Ash.Notifier.PubSub.md", + "documentation/dsls/DSL:-Ash.Policy.Authorizer.md", + "documentation/dsls/DSL:-Ash.DataLayer.Ets.md", + "documentation/dsls/DSL:-Ash.DataLayer.Mnesia.md", + "documentation/dsls/DSL:-Ash.Reactor.md", + "documentation/dsls/DSL:-Ash.DataLayer.Mnesia.md" ], groups_for_extras: [ "Start Here": [ @@ -92,11 +100,13 @@ defmodule Ash.MixProject do "documentation/tutorials/get-started.md" ], Tutorials: [], - Topics: [], + Topics: [ + "documentation/topics/glossary.md" + ], "About Ash": [ - "documentation/topics/what-is-ash.md", - "documentation/topics/design-principles.md", - "documentation/topics/contributing-to-ash.md", + "documentation/topics/about-ash/what-is-ash.md", + "documentation/topics/about_ash/design-principles.md", + "documentation/topics/about_ash/contributing-to-ash.md", "CHANGELOG.md" ], "How To": [], @@ -112,6 +122,7 @@ defmodule Ash.MixProject do ], "Under Review": [ # Documentation below this line is pending review + "documentation/topics/domains.md", "documentation/how_to/define-idiomatic-actions.md", "documentation/how_to/defining-manual-relationships.md", "documentation/how_to/handle-errors.md", @@ -132,7 +143,6 @@ defmodule Ash.MixProject do "documentation/topics/embedded-resources.md", "documentation/topics/extending-resources.md", "documentation/topics/expressions.md", - "documentation/topics/glossary.md", "documentation/topics/identities.md", "documentation/topics/managing-relationships.md", "documentation/topics/manual-actions.md",