docs: clean up docs

README.md

@@ -73,3 +73,18 @@ defmodule Post do
 
   ...
 ```
+
+Then, update your API with the API extension and configuration:
+
+```elixir
+  defmodule MyApp.Api do
+    use Ash.Api, extensions: [AshJsonApi.Api]
+
+    json_api do
+      ...
+    end
+
+  end
+```
+
+See the hex documentation for more.

lib/ash_json_api.ex

@@ -1,6 +1,75 @@
 defmodule AshJsonApi do
   @moduledoc """
-  Tools for introspecting ash json api resources/apis.
+
+  ![Logo](https://github.com/ash-project/ash/blob/master/logos/cropped-for-header.png?raw=true)
+
+  An ash extension for building a JSON:API with ash resources.
+
+  ## Usage
+
+  Assume you have already built a resource using [Ash](https://github.com/ash-project/ash) such as this Post resource:
+
+  ```elixir
+  defmodule Post do
+    use Ash.Resource,
+      data_layer: Ash.DataLayer.Postgres
+
+    actions do
+      read :default
+
+      create :default
+    end
+
+    attributes do
+      attribute :name, :string
+    end
+
+    relationships do
+      belongs_to :author, Author
+    end
+  end
+  ```
+
+  As you can see, the resource takes care of interacting with the database, setting up attributes and relationships, as well as specifying actions (CRUD) that can be performed on the resource. What is now needed is to add a configuration for how this resource will interact with JSON:API
+
+  ```elixir
+  defmodule Post do
+    use Ash.Resource,
+      data_layer: AshPostgres,
+      extensions: [AshJsonApi.Resource]
+
+    ...
+
+    json_api do
+      routes do
+        base "/posts"
+        # Add a `GET /posts/:id` route, that calls into the :read action called :default
+        get :default
+        # Add a `GET /posts` route, that calls into the :read action called :default
+        index :default
+      end
+
+      # Expose these attributes in the API
+      fields [:name]
+    end
+  ...
+  ```
+
+  Then, update your API with the API extension and configuration:
+
+
+  ```elixir
+  defmodule MyApp.Api do
+    use Ash.Api, extensions: [AshJsonApi.Api]
+
+    json_api do
+      ...
+    end
+
+  end
+  ```
+
+  See `AshJsonApi.Api` and `AshJsonApi.Resource` for the DSL documentation.
   """
   alias Ash.Dsl.Extension
 

lib/ash_json_api/controllers/helpers.ex

@@ -1,14 +1,17 @@
 defmodule AshJsonApi.Controllers.Helpers do
-  @moduledoc """
-  Tools for control flow around a request, and common controller utilities.
-
-  While we haven't focused on supporting it yet, this will eventually be a set of tools
-  that can be used to build custom controller actions, without having to write everything
-  yourself.
-
-  `chain/2` lets us pipe cleanly, only doing stateful things if no errors
-  have been generated yet.
-  """
+  @moduledoc false
+  # @moduledoc """
+  # When we open up ash json api tooling to allow people to build custom
+  # behavior around it, we can use this documentation
+  # Tools for control flow around a request, and common controller utilities.
+
+  # While we haven't focused on supporting it yet, this will eventually be a set of tools
+  # that can be used to build custom controller actions, without having to write everything
+  # yourself.
+
+  # `chain/2` lets us pipe cleanly, only doing stateful things if no errors
+  # have been generated yet.
+  # """
   alias AshJsonApi.Controllers.Response
   alias AshJsonApi.{Error, Request}
   alias AshJsonApi.Includes.Includer

lib/ash_json_api/resource/resource.ex

@@ -129,7 +129,7 @@ defmodule AshJsonApi.Resource do
     schema:
       @route_schema
       |> Ash.OptionsHelpers.make_optional!(:route)
-      |> Ash.OptionsHelpers.append_doc!(:route, " Defaults to /:id/<relationship_name>")
+      |> Ash.OptionsHelpers.append_doc!(:route, "Defaults to /:id/[relationship_name]")
       |> Ash.OptionsHelpers.set_type!(:route, {:custom, __MODULE__, :route_with_id, [:get]})
       |> Keyword.put(:relationship,
         type: :atom,
@@ -155,7 +155,7 @@ defmodule AshJsonApi.Resource do
       |> Ash.OptionsHelpers.make_optional!(:route)
       |> Ash.OptionsHelpers.append_doc!(
         :route,
-        " Defaults to /:id/relationships/<relationship_name>"
+        " Defaults to /:id/relationships/[relationship_name]"
       )
       |> Ash.OptionsHelpers.set_type!(:route, {:custom, __MODULE__, :route_with_id, [:get]})
       |> Keyword.put(:relationship,
@@ -182,7 +182,7 @@ defmodule AshJsonApi.Resource do
       |> Ash.OptionsHelpers.make_optional!(:route)
       |> Ash.OptionsHelpers.append_doc!(
         :route,
-        " Defaults to /:id/relationships/<relationship_name>"
+        " Defaults to /:id/relationships/[relationship_name]"
       )
       |> Ash.OptionsHelpers.set_type!(:route, {:custom, __MODULE__, :route_with_id, [:get]})
       |> Keyword.put(:relationship,
@@ -209,7 +209,7 @@ defmodule AshJsonApi.Resource do
       |> Ash.OptionsHelpers.make_optional!(:route)
       |> Ash.OptionsHelpers.append_doc!(
         :route,
-        " Defaults to /:id/relationships/<relationship_name>"
+        " Defaults to /:id/relationships/[relationship_name]"
       )
       |> Ash.OptionsHelpers.set_type!(:route, {:custom, __MODULE__, :route_with_id, [:get]})
       |> Keyword.put(:relationship,
@@ -236,7 +236,7 @@ defmodule AshJsonApi.Resource do
       |> Ash.OptionsHelpers.make_optional!(:route)
       |> Ash.OptionsHelpers.append_doc!(
         :route,
-        " Defaults to /:id/relationships/<relationship_name>"
+        " Defaults to /:id/relationships/[relationship_name]"
       )
       |> Ash.OptionsHelpers.set_type!(:route, {:custom, __MODULE__, :route_with_id, [:get]})
       |> Keyword.put(:relationship,

mix.exs

@@ -16,6 +16,7 @@ defmodule AshJsonApi.MixProject do
       elixirc_paths: elixirc_paths(Mix.env()),
       start_permanent: Mix.env() == :prod,
       test_coverage: [tool: ExCoveralls],
+      docs: docs(),
       preferred_cli_env: [
         coveralls: :test,
         "coveralls.github": :test
@@ -32,11 +33,6 @@ defmodule AshJsonApi.MixProject do
     ]
   end
 
-  defp docs do
-    # The main page in the docs
-    [main: "readme", extras: ["README.md"]]
-  end
-
   defp package do
     [
       name: :ash_json_api,
@@ -47,6 +43,22 @@ defmodule AshJsonApi.MixProject do
     ]
   end
 
+  defp docs do
+    [
+      main: "AshJsonApi",
+      source_ref: "v#{@version}",
+      logo: "logos/small-logo.png",
+      groups_for_modules: [
+        entrypoint: [AshJsonApi],
+        "resource dsl transformers": ~r/AshJsonApi.Resource.Transformers/,
+        "resource dsl": ~r/AshJsonApi.Resource/,
+        "api dsl transformers": ~r/AshJsonApi.Api.Transformers/,
+        "api dsl": ~r/AshJsonApi.Api/,
+        errors: ~r/AshJsonApi.Error/
+      ]
+    ]
+  end
+
   # Run "mix help compile.app" to learn about applications.
   def application do
     [