docs: Rewrite docs for consistent format with other Ash packages (#138)

README.md

@@ -1,135 +1,20 @@
-# AshAdmin
+![Logo](https://github.com/ash-project/ash/blob/main/logos/cropped-for-header-black-text.png?raw=true#gh-light-mode-only)
+![Logo](https://github.com/ash-project/ash/blob/main/logos/cropped-for-header-white-text.png?raw=true#gh-dark-mode-only)
 
-![Elixir CI](https://github.com/ash-project/ash_admin/actions/workflows/elixir.yml/badge.svg)
+![Elixir CI](https://github.com/ash-project/ash_admin/workflows/CI/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Hex version badge](https://img.shields.io/hexpm/v/ash_admin.svg)](https://hex.pm/packages/ash_admin)
+[![Hexdocs badge](https://img.shields.io/badge/docs-hexdocs-purple)](https://hexdocs.pm/ash_admin)
 
-An admin UI for Ash resources. Built with Phoenix LiveView.
+# AshCsv
 
-## Demo
+Welcome! This is a super-admin UI dashboard for [Ash Framework](https://hexdocs.pm/ash) applications, built with Phoenix LiveView.
 
-https://www.youtube.com/watch?v=aFMLz3cpQ8c
+## Tutorials
 
-## Usage
+- [Getting Started with AshAdmin](documentation/tutorials/getting-started-with-ash-admin.md)
 
-First, ensure you've added ash_admin to your `mix.exs` file.
+## Reference
 
-```elixir
-{:ash_admin, "~> 0.10.10-rc.1"}
-```
-
-## Setup
-
-Ensure your domains are configured in `config.exs`
-
-```elixir
-config :my_app, ash_domains: [MyApp.Foo, MyApp.Bar]
-```
-
-Add the admin extension to each domain you want to show in AshAdmin dashboard, and configure it to show. See [`AshAdmin.Domain`](https://hexdocs.pm/ash_admin/AshAdmin.Domain.html) for more configuration options.
-
-```elixir
-# In your Domain(s)
-use Ash.Domain,
-  extensions: [AshAdmin.Domain]
-
-admin do
-  show? true
-end
-```
-
-Resources in each Domain will be included in AshAdmin. See [`AshAdmin.Resource`](https://hexdocs.pm/ash_admin/AshAdmin.Resource.html) for more resource configuration options. Specifically, if you app has an actor you will want to configure that. Ash Admin allows you to change actors and therefore doesn't rely on `Ash.set_actor`
-
-```elixir
-# In your resource that acts as an actor (e.g. User)
-use Ash.Resource,
-  domain: YourDomain,
-  extensions: [AshAdmin.Resource]
-
-  admin do
-    actor?(true)
-  end
-```
-
-Modify your router to add AshAdmin at whatever path you'd like to serve it at.
-
-```elixir
-defmodule MyAppWeb.Router do
-  use Phoenix.Router
-
-  import AshAdmin.Router
-
-  # AshAdmin requires a Phoenix LiveView `:browser` pipeline
-  # If you DO NOT have a `:browser` pipeline already, then AshAdmin has a `:browser` pipeline
-  # Most applications will not need this:
-  admin_browser_pipeline :browser
-
-  scope "/" do
-    # Pipe it through your browser pipeline
-    pipe_through [:browser]
-
-    ash_admin "/admin"
-  end
-end
-```
-
-**Note: there is no builtin security for your AshAdmin (except your apps normal policies). In most cases you will want to secure your AshAdmin routes in some way to prevent them from being public**
-
-Now start your project (usually by running `mix phx.server` in a terminal) and visit `/admin` in your browser (or whatever path you gave to `ash_admin` in your router).
-
-### Content Security Policy
-
-If your app specifies a content security policy header, eg. via
-
-```elixir
-plug :put_secure_browser_headers, %{"content-security-policy" => "default-src 'self'"}
-```
-
-in your router, then all of the styles and JavaScript used to power AshAdmin will be blocked by your browser.
-
-To avoid this, you can add the default AshAdmin nonces to the `default-src` allowlist, ie.
-
-```elixir
-plug :put_secure_browser_headers, %{"content-security-policy" => "default-src 'nonce-ash_admin-Ed55GFnX' 'self'"}
-```
-
-alternatively you can supply your own nonces to the `ash_admin` route by setting a `:csp_nonce_assign_key` in the options list, ie.
-
-```elixir
-ash_admin "/admin", csp_nonce_assign_key: :csp_nonce_value
-```
-
-This will allow AshAdmin-generated inline CSS and JS blocks to execute normally.
-
-## Configuration
-
-See the documentation in [`AshAdmin.Resource`](https://hexdocs.pm/ash_admin/AshAdmin.Resource.html) and [`AshAdmin.Domain`](https://hexdocs.pm/ash_admin/AshAdmin.Domain.html) for information on the available configuration.
-
-## Troubleshooting
-
-If your Admin UI is not responding as expected. Check your browser's developer console for content-security-policy violations (see above).
-
-## Development
-
-To work on ash_admin, you'll want to be able to run the dev app. You'll need to have postgres setup locally, at which point you can do the following:
-
-1. `mix ash_postgres.create`
-2. `mix migrate`
-3. `mix migrate_tenants`
-4. `mix setup`
-
-Then, you can start the app with: `mix dev`
-
-If you make changes to the resources, you can generate migrations with `mix generate_migrations`
-
-If you make changes to any of the assets (CSS or JavaScript), including updating dependencies that include assets such as LiveView, you will need to recompile the assets with `mix assets.deploy`.
-
-## Contributors
-
-Ash is made possible by its excellent community!
-
-<a href="https://github.com/ash-project/ash_admin/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=ash-project/ash_admin" />
-</a>
-
-[Become a contributor](https://ash-hq.org/docs/guides/ash/latest/how_to/contribute.md)
+- [AshAdmin.Domain DSL](documentation/dsls/DSL:-AshAdmin.Domain.md)
+- [AshAdmin.Resource DSL](documentation/dsls/DSL:-AshAdmin.Resource.md)

documentation/dsls/DSL:-AshAdmin.Resource.md

@@ -32,7 +32,7 @@ Configure the admin dashboard for a given resource.
 | [`polymorphic_actions`](#admin-polymorphic_actions){: #admin-polymorphic_actions } | `list(atom)` |  | For resources that use ash_postgres' polymorphism capabilities, you can provide a list of actions that should require a table to be set. If this is not set, then *all* actions will require tables. |
 | [`table_columns`](#admin-table_columns){: #admin-table_columns } | `list(atom)` |  | The list of attributes to render on the table view. |
 | [`format_fields`](#admin-format_fields){: #admin-format_fields } | `list(any)` |  | The list of fields and their formats. |
-| [`relationship_display_fields`](#admin-relationship_display_fields){: #admin-relationship_display_fields } | `list(atom)` |  | The list of attributes to render when it's shown as a relationship on a datatable |
+| [`relationship_display_fields`](#admin-relationship_display_fields){: #admin-relationship_display_fields } | `list(atom)` |  | The list of attributes to render when this resource is shown as a relationship on another resource's datatable. |
 | [`resource_group`](#admin-resource_group){: #admin-resource_group } | `atom` |  | The group in the top resource dropdown that the resource appears in. |
 | [`show_sensitive_fields`](#admin-show_sensitive_fields){: #admin-show_sensitive_fields } | `list(atom)` |  | The list of fields that should not be redacted in the admin UI even if they are marked as sensitive. |
 

documentation/tutorials/contributing-to-ash-admin.md

@@ -0,0 +1,18 @@
+# Contributing to AshAdmin
+
+AshAdmin includes a development app, located in the `dev` folder, so you don't need to have an external Phoenix app to plug AshAdmin into.
+
+You'll need to have PostgreSQL set up locally. Then you can run:
+
+* `mix ash_postgres.create`
+* `mix migrate`
+* `mix migrate_tenants`
+* `mix setup`
+
+Then, you can start the app server with: `mix dev`
+
+If you make changes to the dev resources, you can generate migrations with `mix generate_migrations`
+
+If you make changes to any of the assets (CSS or JavaScript), including updating dependencies that include assets such as Phoenix LiveView, you will need to recompile the assets with `mix assets.deploy`.
+
+For general Ash contribution details, check out [our contribution guide](`e:ash:contributing-to-ash.md`).

documentation/tutorials/getting-started-with-ash-admin.md

@@ -0,0 +1,102 @@
+# Getting Started with AshAdmin
+
+## Demo
+
+https://www.youtube.com/watch?v=aFMLz3cpQ8c
+
+## Installation
+
+Add the `ash_admin` dependency to your `mix.exs` file:
+
+```elixir
+{:ash_admin, "~> 0.10.10-rc.1"}
+```
+
+## Setup
+
+Ensure your domains are configured in `config.exs`:
+
+```elixir
+config :my_app, ash_domains: [MyApp.Foo, MyApp.Bar]
+```
+
+Add the `AshAdmin.Domain` extension to each domain you want to show in the AshAdmin dashboard, and configure it to show. See [DSL: AshAdmin.Domain](/documentation/dsls/DSL:-AshAdmin.Domain.md) for more configuration options.
+
+```elixir
+# In your Domain(s)
+use Ash.Domain,
+  extensions: [AshAdmin.Domain]
+
+admin do
+  show? true
+end
+```
+
+All resources in each Domain will automatically be included in AshAdmin. To configure a resource, use the `AshAdmin.Resource` extension, and then use the [DSL: AshAdmin.Resource](/documentation/dsls/DSL:-AshAdmin.Resource.md) configuration options. Specifically, if your app has an actor you will want to configure that.
+
+```elixir
+# In your resource that acts as an actor (e.g. User)
+use Ash.Resource,
+  domain: YourDomain,
+  extensions: [AshAdmin.Resource]
+
+admin do
+  actor? true
+end
+```
+
+Modify your router to add AshAdmin at whatever path you'd like to serve it at.
+
+```elixir
+defmodule MyAppWeb.Router do
+  use Phoenix.Router
+
+  import AshAdmin.Router
+
+  # AshAdmin requires a Phoenix LiveView `:browser` pipeline
+  # If you DO NOT have a `:browser` pipeline already, then AshAdmin has a `:browser` pipeline
+  # Most applications will not need this:
+  admin_browser_pipeline :browser
+
+  scope "/" do
+    # Pipe it through your browser pipeline
+    pipe_through [:browser]
+
+    ash_admin "/admin"
+  end
+end
+```
+
+> #### Warning {: .warning}
+>
+> There is no builtin security for your AshAdmin (except your app's normal policies). In most cases you will want to secure your AshAdmin routes in some way to prevent them from being publicly accessible.
+
+Start your project (usually by running `mix phx.server` in a terminal) and visit `/admin` in your browser (or the path you configured `ash_admin` with in your router).
+
+### Content Security Policy
+
+If your app specifies a content security policy header, eg. via
+
+```elixir
+plug :put_secure_browser_headers, %{"content-security-policy" => "default-src 'self'"}
+```
+
+in your router, then the stylesheets and JavaScript used to power AshAdmin will be blocked by your browser.
+
+To avoid this, you can add the default AshAdmin nonces to the `default-src` allowlist, ie.
+
+```elixir
+plug :put_secure_browser_headers, %{"content-security-policy" => "default-src 'nonce-ash_admin-Ed55GFnX' 'self'"}
+```
+
+Alternatively you can supply your own nonces to the `ash_admin` route, by setting a `:csp_nonce_assign_key` in the options list, ie.
+
+```elixir
+ash_admin "/admin", csp_nonce_assign_key: :csp_nonce_value
+```
+
+This will allow AshAdmin-generated inline CSS and JS blocks to execute normally.
+
+## Troubleshooting
+
+If your admin UI is not responding as expected, check your browser's developer console for content-security-policy violations (see above).

lib/ash_admin/resource/resource.ex

@@ -79,7 +79,8 @@ defmodule AshAdmin.Resource do
       ],
       relationship_display_fields: [
         type: {:list, :atom},
-        doc: "The list of attributes to render when it's shown as a relationship on a datatable"
+        doc:
+          "The list of attributes to render when this resource is shown as a relationship on another resource's datatable."
       ],
       resource_group: [
         type: :atom,

mix.exs

@@ -2,7 +2,7 @@ defmodule AshAdmin.MixProject do
   use Mix.Project
 
   @description """
-  An admin UI for Ash Framework
+  A super-admin UI for Ash Framework, built with Phoenix LiveView.
   """
 
   @version "0.10.10-rc.1"
@@ -56,6 +56,8 @@ defmodule AshAdmin.MixProject do
       logo: "logos/small-logo.png",
       extras: [
         "README.md",
+        "documentation/tutorials/getting-started-with-ash-admin.md",
+        "documentation/tutorials/contributing-to-ash-admin.md",
         "documentation/dsls/DSL:-AshAdmin.Domain.md",
         "documentation/dsls/DSL:-AshAdmin.Resource.md"
       ],