Auto-generate README File + Scaladoc (#175)

* auto-generate readme file.

* add scaladoc.

* update readme.

* update zio-sbt-website plugin.

* update site workflow.

* remove docs from root project.

* fix build errors.

* update readme.

* update scala version on ci.

* ignore forcing unsupported scala versions.

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: false
       matrix:
         java: ['[email protected]', '[email protected]']
-        scala: ['2.12.16', '2.13.8']
+        scala: ['2.12.17', '2.13.10']
     steps:
     - uses: actions/[email protected]
     - uses: olafurpg/setup-scala@v13
@@ -26,7 +26,7 @@ jobs:
     - name: Lint code
       run: sbt check
     - name: Run tests
-      run: sbt ++${{ matrix.scala }}! test IntegrationTest/test
+      run: sbt ++${{ matrix.scala }} test IntegrationTest/test
 
   website:
     runs-on: ubuntu-20.04

.github/workflows/site.yml

@@ -62,7 +62,7 @@ jobs:
   generate-readme:
     name: Generate README
     runs-on: ubuntu-latest
-    if: ${{ (github.event_name == 'push') || ((github.event_name == 'release') && (github.event_name == 'published')) }}
+    if: ${{ (github.event_name == 'push') || ((github.event_name == 'release') && (github.event.action == 'published')) }}
     steps:
     - name: Git Checkout
       uses: actions/[email protected]

README.md

@@ -6,10 +6,35 @@
 
 ZIO Webhooks is a microlibrary for reliable and persistent webhook delivery.
 
-Below is a state diagram for each webhook handled by a server. Note that there
-aren't any initial or final states as the server doesn't manage the entire
-lifecycle of webhooks and events—only the subset needed for reliable webhook
-delivery.
+[![Development](https://img.shields.io/badge/Project%20Stage-Development-green.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-webhooks/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-webhooks_2.13.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-webhooks_2.13/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-webhooks_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-webhooks_2.13/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-webhooks-docs_2.13/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-webhooks-docs_2.13) [![ZIO Webhooks](https://img.shields.io/github/stars/zio/zio-webhooks?style=social)](https://github.com/zio/zio-webhooks)
+
+## Introduction
+
+Below is a state diagram for each webhook handled by a server. Note that there aren't any initial or final states as the server doesn't manage the entire lifecycle of webhooks and events—only the subset needed for reliable webhook delivery.
+
+## Installation
+
+Include ZIO Webhooks in your project by adding the following to your `build.sbt`:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-webhooks" % "0.2.1"
+```
+
+# Getting Started
+
+There are two ways to start a webhook server: as part of the managed construction of its live layer
+`WebhookServer.live`, or manually by calling `WebhookServer.start`. See [examples](#example-programs) for a list of code
+examples. The managed approach is recommended as it guarantees the server shuts down gracefully. Make sure to
+call `shutdown` on a server created manually. Either way, users will have to implement the following dependencies that are part of `WebhookServer`'s environment:
+
+* [`WebhookRepo`](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookRepo.scala) - to get webhooks and update webhook status;
+* [`WebhookEventRepo`](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookEventRepo.scala) - to subscribe to events and
+  update event status;
+* [`WebhookHttpClient`](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookHttpClient.scala) - to deliver events via HTTP POST
+  (docs/[WebhookSttpClient](https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/backends/sttp/WebhookSttpClient.scala) is provided and ready to use);
+* [`WebhookServerConfig`](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookServerConfig.scala) - to specify settings for
+  error hub capacity, retrying, and batching; and
+* `SerializePayload` - for specifying custom serialization of single and batched event payloads of some content type.
 
 [![](https://mermaid.ink/img/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgRW5hYmxlZCAtLT4gRGlzYWJsZWQgOiBkaXNhYmxlZCBleHRlcm5hbGx5XG4gICAgRW5hYmxlZCAtLT4gRW5hYmxlZCA6IGV2ZW50IGRpc3BhdGNoIHN1Y2Nlc3NcbiAgICBEaXNhYmxlZCAtLT4gRW5hYmxlZCA6IGVuYWJsZWQgZXh0ZXJuYWxseVxuICAgIEVuYWJsZWQgLS0-IFJldHJ5aW5nIDogZXZlbnQgZGlzcGF0Y2ggZmFpbHVyZVxuICAgIFJldHJ5aW5nIC0tPiBFbmFibGVkIDogcmV0cnkgcXVldWUgZW1wdGllZFxuICAgIFJldHJ5aW5nIC0tPiBVbmF2YWlsYWJsZSA6IGNvbnRpbnVvdXMgZmFpbHVyZSBmb3IgZHVyYXRpb24gRFxuICAgIFVuYXZhaWxhYmxlIC0tPiBFbmFibGVkIDogZW5hYmxlZCBleHRlcm5hbGx5XG4gICAgVW5hdmFpbGFibGUgLS0-IERpc2FibGVkIDogZGlzYWJsZWQgZXh0ZXJuYWxseSIsIm1lcm1haWQiOnt9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgRW5hYmxlZCAtLT4gRGlzYWJsZWQgOiBkaXNhYmxlZCBleHRlcm5hbGx5XG4gICAgRW5hYmxlZCAtLT4gRW5hYmxlZCA6IGV2ZW50IGRpc3BhdGNoIHN1Y2Nlc3NcbiAgICBEaXNhYmxlZCAtLT4gRW5hYmxlZCA6IGVuYWJsZWQgZXh0ZXJuYWxseVxuICAgIEVuYWJsZWQgLS0-IFJldHJ5aW5nIDogZXZlbnQgZGlzcGF0Y2ggZmFpbHVyZVxuICAgIFJldHJ5aW5nIC0tPiBFbmFibGVkIDogcmV0cnkgcXVldWUgZW1wdGllZFxuICAgIFJldHJ5aW5nIC0tPiBVbmF2YWlsYWJsZSA6IGNvbnRpbnVvdXMgZmFpbHVyZSBmb3IgZHVyYXRpb24gRFxuICAgIFVuYXZhaWxhYmxlIC0tPiBFbmFibGVkIDogZW5hYmxlZCBleHRlcm5hbGx5XG4gICAgVW5hdmFpbGFibGUgLS0-IERpc2FibGVkIDogZGlzYWJsZWQgZXh0ZXJuYWxseSIsIm1lcm1haWQiOnt9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
 ```mermaid
@@ -24,13 +49,15 @@ stateDiagram-v2
     Unavailable --> Disabled : disabled externally
 ```
 
-## Installation
-
-Include ZIO Webhooks in your project by adding the following to your `build.sbt`:
-
-```scala
-libraryDependencies += "dev.zio" %% "zio-webhooks" % "0.2.1"
-```
+# Example Programs
+
+* [Basic example](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/BasicExample.scala) - most basic usage with the default configuration.
+* [Basic example with batching](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/BasicExampleWithBatching.scala) - same as the basic example but with batching enabled.
+* [Basic example with retrying](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/BasicExampleWithRetrying.scala) - shows how the server retries when an endpoint fails sometimes.
+* [Custom config example](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/CustomConfigExample.scala) - a custom configuration example that also showcases batched retries.
+* [Event recovery example](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/EventRecoveryExample.scala) - shows how the server continues retries after being restarted.
+* [Manual server example](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/ManualServerExample.scala) - shows how to create, start, and shut down a server programmatically.
+* [Shutdown on first error](docs/https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/ShutdownOnFirstError.scala) - shows how to shut down the server on the first error encountered.
 
 ## Documentation
 

build.sbt

@@ -41,7 +41,7 @@ lazy val `zio-webhooks` =
   project
     .in(file("."))
     .settings(publish / skip := true)
-    .aggregate(zioWebhooksCore, zioWebhooksTest, webhooksTestkit, examples, docs)
+    .aggregate(zioWebhooksCore, zioWebhooksTest, webhooksTestkit, examples)
 
 lazy val zioWebhooksCore = module("zio-webhooks-core", "webhooks")
   .enablePlugins(BuildInfoPlugin)

docs/index.md

@@ -6,10 +6,35 @@ sidebar_label: "ZIO Webhooks"
 
 ZIO Webhooks is a microlibrary for reliable and persistent webhook delivery.
 
-Below is a state diagram for each webhook handled by a server. Note that there
-aren't any initial or final states as the server doesn't manage the entire
-lifecycle of webhooks and events—only the subset needed for reliable webhook
-delivery.
+@PROJECT_BADGES@
+
+## Introduction
+
+Below is a state diagram for each webhook handled by a server. Note that there aren't any initial or final states as the server doesn't manage the entire lifecycle of webhooks and events—only the subset needed for reliable webhook delivery.
+
+## Installation
+
+Include ZIO Webhooks in your project by adding the following to your `build.sbt`:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-webhooks" % "@VERSION@"
+```
+
+# Getting Started
+
+There are two ways to start a webhook server: as part of the managed construction of its live layer
+`WebhookServer.live`, or manually by calling `WebhookServer.start`. See [examples](#example-programs) for a list of code
+examples. The managed approach is recommended as it guarantees the server shuts down gracefully. Make sure to
+call `shutdown` on a server created manually. Either way, users will have to implement the following dependencies that are part of `WebhookServer`'s environment:
+
+* [`WebhookRepo`](https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookRepo.scala) - to get webhooks and update webhook status;
+* [`WebhookEventRepo`](https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookEventRepo.scala) - to subscribe to events and
+  update event status;
+* [`WebhookHttpClient`](https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookHttpClient.scala) - to deliver events via HTTP POST
+  ([WebhookSttpClient](https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/backends/sttp/WebhookSttpClient.scala) is provided and ready to use);
+* [`WebhookServerConfig`](https://github.com/zio/zio-webhooks/tree/series/2.x/webhooks/src/main/scala/zio/webhooks/WebhookServerConfig.scala) - to specify settings for
+  error hub capacity, retrying, and batching; and
+* `SerializePayload` - for specifying custom serialization of single and batched event payloads of some content type.
 
 [![](https://mermaid.ink/img/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgRW5hYmxlZCAtLT4gRGlzYWJsZWQgOiBkaXNhYmxlZCBleHRlcm5hbGx5XG4gICAgRW5hYmxlZCAtLT4gRW5hYmxlZCA6IGV2ZW50IGRpc3BhdGNoIHN1Y2Nlc3NcbiAgICBEaXNhYmxlZCAtLT4gRW5hYmxlZCA6IGVuYWJsZWQgZXh0ZXJuYWxseVxuICAgIEVuYWJsZWQgLS0-IFJldHJ5aW5nIDogZXZlbnQgZGlzcGF0Y2ggZmFpbHVyZVxuICAgIFJldHJ5aW5nIC0tPiBFbmFibGVkIDogcmV0cnkgcXVldWUgZW1wdGllZFxuICAgIFJldHJ5aW5nIC0tPiBVbmF2YWlsYWJsZSA6IGNvbnRpbnVvdXMgZmFpbHVyZSBmb3IgZHVyYXRpb24gRFxuICAgIFVuYXZhaWxhYmxlIC0tPiBFbmFibGVkIDogZW5hYmxlZCBleHRlcm5hbGx5XG4gICAgVW5hdmFpbGFibGUgLS0-IERpc2FibGVkIDogZGlzYWJsZWQgZXh0ZXJuYWxseSIsIm1lcm1haWQiOnt9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgRW5hYmxlZCAtLT4gRGlzYWJsZWQgOiBkaXNhYmxlZCBleHRlcm5hbGx5XG4gICAgRW5hYmxlZCAtLT4gRW5hYmxlZCA6IGV2ZW50IGRpc3BhdGNoIHN1Y2Nlc3NcbiAgICBEaXNhYmxlZCAtLT4gRW5hYmxlZCA6IGVuYWJsZWQgZXh0ZXJuYWxseVxuICAgIEVuYWJsZWQgLS0-IFJldHJ5aW5nIDogZXZlbnQgZGlzcGF0Y2ggZmFpbHVyZVxuICAgIFJldHJ5aW5nIC0tPiBFbmFibGVkIDogcmV0cnkgcXVldWUgZW1wdGllZFxuICAgIFJldHJ5aW5nIC0tPiBVbmF2YWlsYWJsZSA6IGNvbnRpbnVvdXMgZmFpbHVyZSBmb3IgZHVyYXRpb24gRFxuICAgIFVuYXZhaWxhYmxlIC0tPiBFbmFibGVkIDogZW5hYmxlZCBleHRlcm5hbGx5XG4gICAgVW5hdmFpbGFibGUgLS0-IERpc2FibGVkIDogZGlzYWJsZWQgZXh0ZXJuYWxseSIsIm1lcm1haWQiOnt9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
 ```mermaid
@@ -24,10 +49,12 @@ stateDiagram-v2
     Unavailable --> Disabled : disabled externally
 ```
 
-## Installation
+# Example Programs
 
-Include ZIO Webhooks in your project by adding the following to your `build.sbt`:
-
-```scala
-libraryDependencies += "dev.zio" %% "zio-webhooks" % "@VERSION@"
-```
+* [Basic example](https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/BasicExample.scala) - most basic usage with the default configuration.
+* [Basic example with batching](https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/BasicExampleWithBatching.scala) - same as the basic example but with batching enabled.
+* [Basic example with retrying](https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/BasicExampleWithRetrying.scala) - shows how the server retries when an endpoint fails sometimes.
+* [Custom config example](https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/CustomConfigExample.scala) - a custom configuration example that also showcases batched retries.
+* [Event recovery example](https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/EventRecoveryExample.scala) - shows how the server continues retries after being restarted.
+* [Manual server example](https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/ManualServerExample.scala) - shows how to create, start, and shut down a server programmatically.
+* [Shutdown on first error](https://github.com/zio/zio-webhooks/tree/series/2.x/examples/src/main/scala/zio/webhooks/example/ShutdownOnFirstError.scala) - shows how to shut down the server on the first error encountered.

docs/sidebars.js

@@ -1,6 +1,12 @@
 const sidebars = {
   sidebar: [
-    "index"
+    {
+      type: "category",
+      label: "ZIO Webhook",
+      collapsed: false,
+      link: { type: "doc", id: "index" },
+      items: [ ]
+    }
   ]
 };
 

project/plugins.sbt

@@ -2,11 +2,7 @@ addSbtPlugin("org.scalameta"      % "sbt-scalafmt"    % "2.5.0")
 addSbtPlugin("pl.project13.scala" % "sbt-jmh"         % "0.4.3")
 addSbtPlugin("com.eed3si9n"       % "sbt-buildinfo"   % "0.11.0")
 addSbtPlugin("org.scoverage"      % "sbt-scoverage"   % "2.0.3")
-addSbtPlugin("org.scalameta"      % "sbt-mdoc"        % "2.3.3")
 addSbtPlugin("ch.epfl.scala"      % "sbt-bloop"       % "1032048a")
-addSbtPlugin("com.eed3si9n"       % "sbt-unidoc"      % "0.4.3")
 addSbtPlugin("com.geirsson"       % "sbt-ci-release"  % "1.5.7")
 addSbtPlugin("ch.epfl.scala"      % "sbt-scalafix"    % "0.10.4")
-addSbtPlugin("dev.zio"            % "zio-sbt-website" % "0.3.4")
-
-resolvers += Resolver.sonatypeRepo("public")
+addSbtPlugin("dev.zio"            % "zio-sbt-website" % "0.3.10")