From 1e0ebfd0d25bf8a553a383906612a9e23b67870c Mon Sep 17 00:00:00 2001 From: Zach Daniel Date: Fri, 3 May 2024 15:29:28 -0400 Subject: [PATCH] docs: docs overhaul --- README.md | 26 ++++++++++--------- config/config.exs | 2 +- documentation/dsls/DSL:-AshOban.md | 2 +- ...an.md => getting-started-with-ash-oban.md} | 13 ++-------- lib/ash_oban.ex | 2 +- mix.exs | 7 ++--- 6 files changed, 23 insertions(+), 29 deletions(-) rename documentation/tutorials/{get-started-with-ash-oban.md => getting-started-with-ash-oban.md} (96%) diff --git a/README.md b/README.md index 09a8e4c..8f23235 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ -# AshOban +![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) -An oban extension for `Ash.Resource` +![Elixir CI](https://github.com/ash-project/ash_oban/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_oban.svg)](https://hex.pm/packages/ash_oban) +[![Hexdocs badge](https://img.shields.io/badge/docs-hexdocs-purple)](https://hexdocs.pm/ash_oban) -## Installation +# AshGraphql -```elixir -def deps do - [ - {:ash_oban, "~> 0.2.3-rc.1"} - ] -end -``` +Welcome! This is the extension for integrating [Ash](https://hexdocs.pm/ash) resources with [Oban](https://hexdocs.pm/oban). This extension allows you to easily execute resource actions in the background, and trigger actions based on data conditions. -## Get Started +## Tutorials -Check out the [getting started guide](/documentation/tutorials/get-started-with-ash-oban.md). +- [Getting Started with AshOban](documentation/tutorials/getting-started-with-ash-oban.md) + +## Reference + +- [AshOban DSL](documentation/dsls/DSL:-AshOban.md) diff --git a/config/config.exs b/config/config.exs index 2d24a6b..4254186 100644 --- a/config/config.exs +++ b/config/config.exs @@ -50,7 +50,7 @@ if Mix.env() == :dev do # Pass in `true` to use `"README.md"` or a string to customize manage_readme_version: [ "README.md", - "documentation/tutorials/get-started-with-ash-oban.md" + "documentation/tutorials/getting-started-with-ash-oban.md" ], version_tag_prefix: "v" end diff --git a/documentation/dsls/DSL:-AshOban.md b/documentation/dsls/DSL:-AshOban.md index beedb51..ee2c0b0 100644 --- a/documentation/dsls/DSL:-AshOban.md +++ b/documentation/dsls/DSL:-AshOban.md @@ -98,7 +98,7 @@ end | [`scheduler_queue`](#oban-triggers-trigger-scheduler_queue){: #oban-triggers-trigger-scheduler_queue } | `atom` | | The queue to place the scheduler job in. The same queue as job is used by default (but with a priority of 1 so schedulers run first). | | [`debug?`](#oban-triggers-trigger-debug?){: #oban-triggers-trigger-debug? } | `boolean` | `false` | If set to `true`, detailed debug logging will be enabled for this trigger. You can also set `config :ash_oban, debug_all_triggers?: true` to enable debug logging for all triggers. | | [`scheduler_cron`](#oban-triggers-trigger-scheduler_cron){: #oban-triggers-trigger-scheduler_cron } | `String.t \| false` | `"* * * * *"` | A crontab configuration for when the job should run. Defaults to once per minute ("* * * * *"). Use `false` to disable the scheduler entirely. | -| [`stream_batch_size`](#oban-triggers-trigger-stream_batch_size){: #oban-triggers-trigger-stream_batch_size } | `pos_integer` | | The batch size to pass when streaming records from using `c:Ash.stream!/2`. No batch size is passed if none is provided here, so the default is used. | +| [`stream_batch_size`](#oban-triggers-trigger-stream_batch_size){: #oban-triggers-trigger-stream_batch_size } | `pos_integer` | | The batch size to pass when streaming records from using `Ash.stream!/2`. No batch size is passed if none is provided here, so the default is used. | | [`queue`](#oban-triggers-trigger-queue){: #oban-triggers-trigger-queue } | `atom` | | The queue to place the worker job in. The trigger name is used by default. | | [`record_limit`](#oban-triggers-trigger-record_limit){: #oban-triggers-trigger-record_limit } | `pos_integer` | | If set, any given run of the scheduler will only ever schedule this many items maximum | | [`log_errors?`](#oban-triggers-trigger-log_errors?){: #oban-triggers-trigger-log_errors? } | `boolean` | `true` | Whether or not to log errors that occur when performing an action. | diff --git a/documentation/tutorials/get-started-with-ash-oban.md b/documentation/tutorials/getting-started-with-ash-oban.md similarity index 96% rename from documentation/tutorials/get-started-with-ash-oban.md rename to documentation/tutorials/getting-started-with-ash-oban.md index d552595..2779a2e 100644 --- a/documentation/tutorials/get-started-with-ash-oban.md +++ b/documentation/tutorials/getting-started-with-ash-oban.md @@ -1,4 +1,4 @@ -# Get Started With Ash Oban +# Getting Started With Ash Oban AshOban will likely grow to provide many more oban-related features, but for now the primary focus is on "triggers". @@ -8,19 +8,10 @@ A trigger describes an action that is run periodically. If you haven't already, read the [Ash Getting Started Guide](https://hexdocs.pm/ash/get-started.html), and familiarize yourself with Ash and Ash resources. -## Notice - -Potential breaking change from `0.1.0` to `0.2.0`. See the section on Authorization Actions below for more. - ## Bring in the `ash_oban` dependency ```elixir -def deps() - [ - ... - {:ash_oban, "~> 0.2.3-rc.1"} - ] -end +{:ash_oban, "~> 0.2.3-rc.1"} ``` ## Setup diff --git a/lib/ash_oban.ex b/lib/ash_oban.ex index 02aa8d2..ae3fe9c 100644 --- a/lib/ash_oban.ex +++ b/lib/ash_oban.ex @@ -113,7 +113,7 @@ defmodule AshOban do stream_batch_size: [ type: :pos_integer, doc: - "The batch size to pass when streaming records from using `c:Ash.stream!/2`. No batch size is passed if none is provided here, so the default is used." + "The batch size to pass when streaming records from using `Ash.stream!/2`. No batch size is passed if none is provided here, so the default is used." ], queue: [ type: :atom, diff --git a/mix.exs b/mix.exs index 1d03b15..f4cf220 100644 --- a/mix.exs +++ b/mix.exs @@ -4,7 +4,7 @@ defmodule AshOban.MixProject do @version "0.2.3-rc.1" @description """ - An Ash.Resource extension for integrating with Oban. + The extension for integrating Ash resources with Oban. """ def project do @@ -57,12 +57,13 @@ defmodule AshOban.MixProject do defp docs do [ - main: "get-started-with-ash-oban", + main: "readme", source_ref: "v#{@version}", logo: "logos/small-logo.png", extra_section: "GUIDES", extras: [ - "documentation/tutorials/get-started-with-ash-oban.md", + {"README.md", title: "Home"}, + "documentation/tutorials/getting-started-with-ash-oban.md", "documentation/dsls/DSL:-AshOban.md" ], groups_for_extras: [