Skip to content

Commit

Permalink
Add Scaladoc Support (#177)
Browse files Browse the repository at this point in the history
  • Loading branch information
khajavi authored Jan 16, 2023
1 parent c9090a8 commit 067308d
Show file tree
Hide file tree
Showing 4 changed files with 136 additions and 76 deletions.
116 changes: 93 additions & 23 deletions .github/workflows/site.yml
Original file line number Diff line number Diff line change
@@ -1,28 +1,98 @@
# This file was autogenerated using `zio-sbt` via `sbt generateGithubWorkflow`
# task and should be included in the git repository. Please do not edit
# it manually.
# This file was autogenerated using `zio-sbt-website` via `sbt generateGithubWorkflow`
# task and should be included in the git repository. Please do not edit it manually.

name: website

on:
name: Website
'on':
workflow_dispatch: {}
release:
types: [ published ]

types:
- published
push:
branches:
- series/2.x
pull_request: {}
jobs:
build:
name: Build and Test
runs-on: ubuntu-latest
if: ${{ github.event_name == 'pull_request' }}
steps:
- name: Git Checkout
uses: actions/checkout@v3.3.0
with:
fetch-depth: '0'
- name: Setup Scala
uses: actions/setup-java@v3.9.0
with:
distribution: temurin
java-version: 17
check-latest: true
- name: Check if the README file is up to date
run: sbt docs/checkReadme
- name: Check if the site workflow is up to date
run: sbt docs/checkGithubWorkflow
- name: Check artifacts build process
run: sbt +publishLocal
- name: Check website build process
run: sbt docs/clean; sbt docs/buildWebsite
publish-docs:
runs-on: ubuntu-20.04
timeout-minutes: 30
name: Publish Docs
runs-on: ubuntu-latest
if: ${{ ((github.event_name == 'release') && (github.event.action == 'published')) || (github.event_name == 'workflow_dispatch') }}
steps:
- uses: actions/checkout@v3.1.0
with:
fetch-depth: 0
- name: Setup Scala and Java
uses: olafurpg/setup-scala@v13
- uses: actions/setup-node@v3
with:
node-version: '16.x'
registry-url: 'https://registry.npmjs.org'
- name: Publishing Docs to NPM Registry
run: sbt docs/publishToNpm
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Git Checkout
uses: actions/checkout@v3.3.0
with:
fetch-depth: '0'
- name: Setup Scala
uses: actions/setup-java@v3.9.0
with:
distribution: temurin
java-version: 17
check-latest: true
- name: Setup NodeJs
uses: actions/setup-node@v3
with:
node-version: 16.x
registry-url: https://registry.npmjs.org
- name: Publish Docs to NPM Registry
run: sbt docs/publishToNpm
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
generate-readme:
name: Generate README
runs-on: ubuntu-latest
if: ${{ (github.event_name == 'push') || ((github.event_name == 'release') && (github.event_name == 'published')) }}
steps:
- name: Git Checkout
uses: actions/checkout@v3.3.0
with:
ref: ${{ github.head_ref }}
fetch-depth: '0'
- name: Setup Scala
uses: actions/setup-java@v3.9.0
with:
distribution: temurin
java-version: 17
check-latest: true
- name: Generate Readme
run: sbt docs/generateReadme
- name: Commit Changes
run: |
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git add README.md
git commit -m "Update README.md" || echo "No changes to commit"
- name: Create Pull Request
uses: peter-evans/create-pull-request@v4.2.3
with:
body: |-
Autogenerated changes after running the `sbt docs/generateReadme` command of the [zio-sbt-website](https://zio.dev/zio-sbt) plugin.
I will automatically update the README.md file whenever there is new change for README.md, e.g.
- After each release, I will update the version in the installation section.
- After any changes to the "docs/index.md" file, I will update the README.md file accordingly.
branch: zio-sbt-website/update-readme
commit-message: Update README.md
delete-branch: true
title: Update README.md
78 changes: 34 additions & 44 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,44 @@
# zio-webhooks
[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.)
[//]: # (So please do not edit it manually. Instead, change "docs/index.md" file or sbt setting keys)
[//]: # (e.g. "readmeDocumentation" and "readmeSupport".)

| Project Stage | CI | Release | Snapshot | Discord |
| --- | --- | --- | --- | --- |
| [![Project stage][Stage]][Stage-Page] | ![CI][Badge-CI] | [![Release Artifacts][Badge-SonatypeReleases]][Link-SonatypeReleases] | [![Snapshot Artifacts][Badge-SonatypeSnapshots]][Link-SonatypeSnapshots] | [![Badge-Discord]][Link-Discord] |
# ZIO Webhooks

# Summary
ZIO Webhooks is a microlibrary for reliable and persistent webhook delivery.

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.

# Getting Started
[![](https://mermaid.ink/img/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgRW5hYmxlZCAtLT4gRGlzYWJsZWQgOiBkaXNhYmxlZCBleHRlcm5hbGx5XG4gICAgRW5hYmxlZCAtLT4gRW5hYmxlZCA6IGV2ZW50IGRpc3BhdGNoIHN1Y2Nlc3NcbiAgICBEaXNhYmxlZCAtLT4gRW5hYmxlZCA6IGVuYWJsZWQgZXh0ZXJuYWxseVxuICAgIEVuYWJsZWQgLS0-IFJldHJ5aW5nIDogZXZlbnQgZGlzcGF0Y2ggZmFpbHVyZVxuICAgIFJldHJ5aW5nIC0tPiBFbmFibGVkIDogcmV0cnkgcXVldWUgZW1wdGllZFxuICAgIFJldHJ5aW5nIC0tPiBVbmF2YWlsYWJsZSA6IGNvbnRpbnVvdXMgZmFpbHVyZSBmb3IgZHVyYXRpb24gRFxuICAgIFVuYXZhaWxhYmxlIC0tPiBFbmFibGVkIDogZW5hYmxlZCBleHRlcm5hbGx5XG4gICAgVW5hdmFpbGFibGUgLS0-IERpc2FibGVkIDogZGlzYWJsZWQgZXh0ZXJuYWxseSIsIm1lcm1haWQiOnt9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgRW5hYmxlZCAtLT4gRGlzYWJsZWQgOiBkaXNhYmxlZCBleHRlcm5hbGx5XG4gICAgRW5hYmxlZCAtLT4gRW5hYmxlZCA6IGV2ZW50IGRpc3BhdGNoIHN1Y2Nlc3NcbiAgICBEaXNhYmxlZCAtLT4gRW5hYmxlZCA6IGVuYWJsZWQgZXh0ZXJuYWxseVxuICAgIEVuYWJsZWQgLS0-IFJldHJ5aW5nIDogZXZlbnQgZGlzcGF0Y2ggZmFpbHVyZVxuICAgIFJldHJ5aW5nIC0tPiBFbmFibGVkIDogcmV0cnkgcXVldWUgZW1wdGllZFxuICAgIFJldHJ5aW5nIC0tPiBVbmF2YWlsYWJsZSA6IGNvbnRpbnVvdXMgZmFpbHVyZSBmb3IgZHVyYXRpb24gRFxuICAgIFVuYXZhaWxhYmxlIC0tPiBFbmFibGVkIDogZW5hYmxlZCBleHRlcm5hbGx5XG4gICAgVW5hdmFpbGFibGUgLS0-IERpc2FibGVkIDogZGlzYWJsZWQgZXh0ZXJuYWxseSIsIm1lcm1haWQiOnt9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
```mermaid
stateDiagram-v2
Enabled --> Disabled : disabled externally
Enabled --> Enabled : event dispatch success
Disabled --> Enabled : enabled externally
Enabled --> Retrying : event dispatch failure
Retrying --> Enabled : retry queue emptied
Retrying --> Unavailable : continuous failure for duration D
Unavailable --> Enabled : enabled externally
Unavailable --> Disabled : disabled externally
```

## Installation

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:
Include ZIO Webhooks in your project by adding the following to your `build.sbt`:

* [`WebhookRepo`](/webhooks/src/main/scala/zio/webhooks/WebhookRepo.scala) - to get webhooks and update webhook status;
* [`WebhookEventRepo`](/webhooks/src/main/scala/zio/webhooks/WebhookEventRepo.scala) - to subscribe to events and
update event status;
* [`WebhookHttpClient`](/webhooks/src/main/scala/zio/webhooks/WebhookHttpClient.scala) - to deliver events via HTTP POST
([WebhookSttpClient](/webhooks/src/main/scala/zio/webhooks/backends/sttp/WebhookSttpClient.scala) is provided and ready to use);
* [`WebhookServerConfig`](/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.
```scala
libraryDependencies += "dev.zio" %% "zio-webhooks" % "0.2.1"
```

# Example Programs
## Documentation

* [Basic example](/examples/src/main/scala/zio/webhooks/example/BasicExample.scala) - most basic usage with the default configuration.
* [Basic example with batching](/examples/src/main/scala/zio/webhooks/example/BasicExampleWithBatching.scala) - same as the basic example but with batching enabled.
* [Basic example with retrying](/examples/src/main/scala/zio/webhooks/example/BasicExampleWithRetrying.scala) - shows how the server retries when an endpoint fails sometimes.
* [Custom config example](/examples/src/main/scala/zio/webhooks/example/CustomConfigExample.scala) - a custom configuration example that also showcases batched retries.
* [Event recovery example](/examples/src/main/scala/zio/webhooks/example/EventRecoveryExample.scala) - shows how the server continues retries after being restarted.
* [Manual server example](/examples/src/main/scala/zio/webhooks/example/ManualServerExample.scala) - shows how to create, start, and shut down a server programmatically.
* [Shutdown on first error](/examples/src/main/scala/zio/webhooks/example/ShutdownOnFirstError.scala) - shows how to shut down the server on the first error encountered.
Learn more on the [ZIO Webhooks homepage](https://zio.dev/zio-webhooks/)!

# Documentation
## Contributing

[ZIO Webhooks Microsite](https://zio.dev/zio-webhooks/)

# Contributing

[Documentation for contributors](https://zio.dev/about/contributing)
For the general guidelines, see ZIO [contributor's guide](https://zio.dev/about/contributing).

## Code of Conduct

Expand All @@ -50,17 +48,9 @@ See the [Code of Conduct](https://zio.dev/about/code-of-conduct)

Come chat with us on [![Badge-Discord]][Link-Discord].

# License

[License](LICENSE)

[Badge-SonatypeReleases]: https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-webhooks_2.12.svg "Sonatype Releases"
[Badge-SonatypeSnapshots]: https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-webhooks_2.12.svg "Sonatype Snapshots"
[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord "chat on discord"
[Link-SonatypeReleases]: https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-webhooks_2.12/ "Sonatype Releases"
[Link-SonatypeSnapshots]: https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-webhooks_2.12/ "Sonatype Snapshots"
[Link-Discord]: https://discord.gg/2ccFBr4 "Discord"
[Badge-CI]: https://github.com/zio/zio-webhooks/workflows/CI/badge.svg
[Stage]: https://img.shields.io/badge/Project%20Stage-Development-green.svg
[Stage-Page]: https://github.com/zio/zio/wiki/Project-Stages

## License

[License](LICENSE)
16 changes: 8 additions & 8 deletions build.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ lazy val `zio-webhooks` =
project
.in(file("."))
.settings(publish / skip := true)
.aggregate(zioWebhooksCore, zioWebhooksTest, webhooksTestkit, examples)
.aggregate(zioWebhooksCore, zioWebhooksTest, webhooksTestkit, examples, docs)

lazy val zioWebhooksCore = module("zio-webhooks-core", "webhooks")
.enablePlugins(BuildInfoPlugin)
Expand Down Expand Up @@ -102,21 +102,21 @@ def module(moduleName: String, fileName: String): Project =
Project(moduleName, file(fileName))
.settings(stdSettings(moduleName))
.settings(
libraryDependencies ++= Seq(
"dev.zio" %% "zio" % zioVersion
)
libraryDependencies ++= Seq("dev.zio" %% "zio" % zioVersion)
)

lazy val docs = project
.in(file("zio-webhooks-docs"))
.settings(
publish / skip := true,
moduleName := "zio-webhooks-docs",
scalacOptions -= "-Yno-imports",
scalacOptions -= "-Xfatal-warnings",
libraryDependencies ++= Seq(
"dev.zio" %% "zio" % zioVersion
)
libraryDependencies ++= Seq("dev.zio" %% "zio" % zioVersion),
projectName := "ZIO Webhooks",
mainModuleName := (zioWebhooksCore / moduleName).value,
projectStage := ProjectStage.Development,
ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(zioWebhooksCore),
docsPublishBranch := "series/2.x"
)
.dependsOn(zioWebhooksCore)
.enablePlugins(WebsitePlugin)
2 changes: 1 addition & 1 deletion project/plugins.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,6 @@ 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.0.0+84-6fd7d64e-SNAPSHOT")
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.3.4")

resolvers += Resolver.sonatypeRepo("public")

0 comments on commit 067308d

Please sign in to comment.