Docs cosmetics (#505)

.github/workflows/master.yml

@@ -8,5 +8,6 @@ jobs:
     uses: ThreeDotsLabs/watermill/.github/workflows/tests.yml@master
     with:
       stress-tests: true
+      codecov: true
     secrets:
       codecov_token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/pr.yml

@@ -4,3 +4,7 @@ on:
 jobs:
   ci:
     uses: ThreeDotsLabs/watermill/.github/workflows/tests.yml@master
+    with:
+      codecov: true
+    secrets:
+      codecov_token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/tests.yml

@@ -7,6 +7,10 @@ on:
         required: false
         type: boolean
         default: false
+      codecov:
+        required: false
+        type: boolean
+        default: false
     secrets:
       codecov_token:
         required: false
@@ -57,6 +61,7 @@ jobs:
       - run: make wait
       - run: make test_codecov
       - uses: codecov/codecov-action@v4
+        if: ${{ inputs.codecov }}
         with:
           fail_ci_if_error: true
           files: ./coverage.out

docs/config/_default/params.toml

@@ -120,7 +120,7 @@ mainSections = ["docs"]
 [seo]
   [seo.title]
     separator = " | "
-    suffix = ""
+    suffix = "Watermill | Event-Driven in Go"
   [seo.favicons]
     sizes = []
     icon = "favicon.png" # favicon.png (default)

docs/config/production/hugo.toml

@@ -1,2 +1 @@
 # Overrides for production environment
-baseurl = "https://watermill.io/"

docs/content/pubsubs/amqp.md

@@ -12,13 +12,15 @@ We are providing Pub/Sub implementation based on [github.com/rabbitmq/amqp091-go
 
 {{% load-snippet-partial file="src-link/watermill-amqp/pkg/amqp/doc.go" first_line_contains="// AMQP" last_line_contains="package amqp" padding_after="0" %}}
 
-### Installation
+You can find a fully functional example with RabbitMQ in the [Watermill examples](https://github.com/ThreeDotsLabs/watermill/tree/master/_examples/pubsubs/amqp).
+
+## Installation
 
 ```bash
 go get github.com/ThreeDotsLabs/watermill-amqp/v3
 ```
 
-#### Characteristics
+### Characteristics
 
 | Feature | Implements | Note |
 | ------- | ---------- | ---- |
@@ -27,33 +29,33 @@ go get github.com/ThreeDotsLabs/watermill-amqp/v3
 | GuaranteedOrder | yes |  yes, please check https://www.rabbitmq.com/semantics.html#ordering |
 | Persistent | yes* | when using `NewDurablePubSubConfig` or `NewDurableQueueConfig`  |
 
-#### Configuration
+### Configuration
 
 Our AMQP is shipped with some pre-created configurations:
 
 {{% load-snippet-partial file="src-link/watermill-amqp/pkg/amqp/config.go" first_line_contains="// NewDurablePubSubConfig" last_line_contains="type Config struct {" %}}
 
 For detailed configuration description, please check [watermill-amqp/pkg/amqp/config.go](https://github.com/ThreeDotsLabs/watermill-amqp/tree/master/pkg/amqp/config.go)
 
-##### TLS Config
+#### TLS Config
 
 TLS config can be passed to `Config.TLSConfig`.
 
-##### Connecting
+#### Connecting
 
 {{% load-snippet-partial file="src-link/_examples/pubsubs/amqp/main.go" first_line_contains="publisher, err :=" last_line_contains="panic(err)" padding_after="1" %}}
 
 {{% load-snippet-partial file="src-link/_examples/pubsubs/amqp/main.go" first_line_contains="subscriber, err :=" last_line_contains="panic(err)" padding_after="1" %}}
 
-#### Publishing
+### Publishing
 
 {{% load-snippet-partial file="src-link/watermill-amqp/pkg/amqp/publisher.go" first_line_contains="// Publish" last_line_contains="func (p *Publisher) Publish" %}}
 
-#### Subscribing
+### Subscribing
 
 {{% load-snippet-partial file="src-link/watermill-amqp/pkg/amqp/subscriber.go" first_line_contains="// Subscribe" last_line_contains="func (s *Subscriber) Subscribe" %}}
 
-#### Marshaler
+### Marshaler
 
 Marshaler is responsible for mapping AMQP's messages to Watermill's messages.
 
@@ -62,15 +64,14 @@ If you need to customize thing in `amqp.Delivery`, you can do it `PostprocessPub
 
 {{% load-snippet-partial file="src-link/watermill-amqp/pkg/amqp/marshaler.go" first_line_contains="// Marshaler" last_line_contains="func (d DefaultMarshaler)" padding_after="0" %}}
 
-#### AMQP "Consumer Groups"
+### AMQP "Consumer Groups"
 
 AMQP doesn't provide mechanism like Kafka's "consumer groups". You can still achieve similar behaviour with `GenerateQueueNameTopicNameWithSuffix` and `NewDurablePubSubConfig`.
 
 {{% load-snippet-partial file="docs/snippets/amqp-consumer-groups/main.go" first_line_contains="func createSubscriber(" last_line_contains="go process(\"subscriber_2\", messages2)" %}}
 
 In this example both `pubSub1` and `pubSub2` will receive some messages independently.
 
-#### AMQP `TopologyBuilder`
+### AMQP `TopologyBuilder`
 
 {{% load-snippet-partial file="src-link/watermill-amqp/pkg/amqp/topology_builder.go" first_line_contains="// TopologyBuilder" last_line_contains="}" padding_after="0" %}}
-

docs/content/pubsubs/bolt.md

@@ -16,13 +16,13 @@ want to publish messages in transaction when saving other data.
 
 Bolt documentation: https://github.com/etcd-io/bbolt
 
-### Installation
+## Installation
 
 ```bash
 go get github.com/ThreeDotsLabs/watermill-bolt
 ```
 
-#### Characteristics
+### Characteristics
 
 | Feature             | Implements | Note |
 | ------------------- | ---------- | ---- |
@@ -31,15 +31,15 @@ go get github.com/ThreeDotsLabs/watermill-bolt
 | GuaranteedOrder     | no         |      |
 | Persistent          | yes        |      |
 
-#### Configuration
+### Configuration
 
 {{% load-snippet-partial file="src-link/watermill-bolt/pkg/bolt/bolt.go" first_line_contains="type CommonConfig struct " last_line_equals="}" %}}
 
 {{% load-snippet-partial file="src-link/watermill-bolt/pkg/bolt/bolt.go" first_line_contains="type PublisherConfig struct " last_line_equals="}" %}}
 
 {{% load-snippet-partial file="src-link/watermill-bolt/pkg/bolt/bolt.go" first_line_contains="type SubscriberConfig struct " last_line_equals="}" %}}
 
-##### Subscription name
+#### Subscription name
 
 To receive messages published to a topic, you must create a subscription to
 that topic. Only messages published to the topic after the subscription is
@@ -53,7 +53,7 @@ In Watermill, the subscription is created automatically during calling
 `SubscriberConfig.GenerateSubscriptionName`.  By default, it is the topic name
 with the string `_sub` appended to it.
 
-##### Marshaler
+#### Marshaler
 
 Watermill's messages cannot be directly saved in Bolt which operates on byte
 slices. Marshaller converts the messages to and from byte slices. The default
@@ -63,5 +63,3 @@ unless a very large messages are used within your system. If that is the case
 you may want to consider implementing a more efficient marshaler.
 
 {{% load-snippet-partial file="src-link/watermill-bolt/pkg/bolt/marshaler.go" first_line_contains="// Marshaler" last_line_equals="}" %}}
-
-

docs/content/pubsubs/firestore.md

@@ -25,13 +25,13 @@ Godoc: <https://pkg.go.dev/github.com/ThreeDotsLabs/watermill-firestore>
 
 Firestore documentation: <https://firebase.google.com/docs/firestore/>
 
-### Installation
+## Installation
 
 ```bash
 go get github.com/ThreeDotsLabs/watermill-firestore
 ```
 
-#### Characteristics
+### Characteristics
 
 | Feature             | Implements | Note |
 | -------             | ---------- | ---- |
@@ -40,17 +40,17 @@ go get github.com/ThreeDotsLabs/watermill-firestore
 | GuaranteedOrder     | no         |      |
 | Persistent          | yes        |      |
 
-#### Configuration
+### Configuration
 
-##### Publisher configuration
+#### Publisher configuration
 
 {{% load-snippet-partial file="src-link/watermill-firestore/pkg/firestore/publisher.go" first_line_contains="type PublisherConfig struct {" last_line_equals="}" %}}
 
-##### Subscriber configuration
+#### Subscriber configuration
 
 {{% load-snippet-partial file="src-link/watermill-firestore/pkg/firestore/subscriber.go" first_line_contains="type SubscriberConfig struct {" last_line_equals="}" %}}
 
-##### Subscription name
+#### Subscription name
 
 To receive messages published to a topic, you must create a subscription to
 that topic. Only messages published to the topic after the subscription is
@@ -68,13 +68,11 @@ If you want to consume messages from a topic with multiple subscribers
 processing the incoming messages in a different way, you should use a custom
 function to generate unique subscription names for each subscriber.
 
-#### Marshaler
+### Marshaler
 
 Watermill's messages cannot be stored directly in Firestore. The marshaler is
 responsible for converting them to a type which can be stored by Firestore.
 The default implementation should be enough for most applications so it is
 unlikely that you need to implement your own marshaler.
 
 {{% load-snippet-partial file="src-link/watermill-firestore/pkg/firestore/marshaler.go" first_line_contains="// Marshaler" last_line_equals="}" padding_after="0" %}}
-
-

docs/content/pubsubs/gochannel.md

@@ -8,7 +8,9 @@ weight = 40
 
 {{% load-snippet-partial file="src-link/pubsub/gochannel/pubsub.go" first_line_contains="// GoChannel" last_line_contains="type GoChannel struct {" %}}
 
-#### Characteristics
+You can find a fully functional example with Go Channels in the [Watermill examples](https://github.com/ThreeDotsLabs/watermill/tree/master/_examples/pubsubs/go-channel).
+
+### Characteristics
 
 | Feature | Implements | Note |
 | ------- | ---------- | ---- |
@@ -17,21 +19,20 @@ weight = 40
 | GuaranteedOrder | yes |  |
 | Persistent | no| |
 
-#### Configuration
+### Configuration
 
 You can inject configuration via the constructor.
 
 {{% load-snippet-partial file="src-link/pubsub/gochannel/pubsub.go" first_line_contains="func NewGoChannel" last_line_contains="logger:" %}}
 
-#### Publishing
+### Publishing
 
 {{% load-snippet-partial file="src-link/pubsub/gochannel/pubsub.go" first_line_contains="// Publish" last_line_contains="func (g *GoChannel) Publish" %}}
 
-#### Subscribing
+### Subscribing
 
 {{% load-snippet-partial file="src-link/pubsub/gochannel/pubsub.go" first_line_contains="// Subscribe" last_line_contains="func (g *GoChannel) Subscribe" %}}
 
-#### Marshaler
+### Marshaler
 
 No marshaling is needed when sending messages within the process.
-

docs/content/pubsubs/googlecloud.md

@@ -17,15 +17,17 @@ it allows for secure and highly available communication among independently writ
 Cloud Pub/Sub delivers low-latency, durable messaging that helps developers quickly integrate
 systems hosted on the Google Cloud Platform and externally.
 
-Documentation: [https://cloud.google.com/pubsub/docs/](https://cloud.google.com/pubsub/docs/overview)
+Official Documentation: [https://cloud.google.com/pubsub/docs/](https://cloud.google.com/pubsub/docs/overview)
 
-### Installation
+You can find a fully functional example with Google Cloud Pub/Sub in the [Watermill examples](https://github.com/ThreeDotsLabs/watermill/tree/master/_examples/pubsubs/googlecloud).
+
+## Installation
 
 ```bash
 go get github.com/ThreeDotsLabs/watermill-googlecloud
 ```
 
-#### Characteristics
+### Characteristics
 
 | Feature | Implements | Note |
 | ------- | ---------- | ---- |
@@ -34,13 +36,13 @@ go get github.com/ThreeDotsLabs/watermill-googlecloud
 | GuaranteedOrder | no | |
 | Persistent | yes* | maximum retention time is 7 days |
 
-#### Configuration
+### Configuration
 
 {{% load-snippet-partial file="src-link/watermill-googlecloud/pkg/googlecloud/publisher.go" first_line_contains="type PublisherConfig struct " last_line_contains="func NewPublisher" %}}
 
 {{% load-snippet-partial file="src-link/watermill-googlecloud/pkg/googlecloud/subscriber.go" first_line_contains="type SubscriberConfig struct {" last_line_contains="func NewSubscriber(" %}}
 
-##### Subscription name
+#### Subscription name
 
 To receive messages published to a topic, you must create a subscription to that topic.
 Only messages published to the topic after the subscription is created are available to subscriber
@@ -58,7 +60,7 @@ By default, it is just the topic name (`TopicSubscriptionName`).
 When you want to consume messages from a topic with multiple subscribers, you should use
 `TopicSubscriptionNameWithSuffix` or your custom function to generate the subscription name.
 
-#### Connecting
+### Connecting
 
 Watermill will connect to the instance of Google Cloud Pub/Sub indicated by the environment variables. For production setup, set the `GOOGLE_APPLICATION_CREDENTIALS` env, as described in [the official Google Cloud Pub/Sub docs](https://cloud.google.com/pubsub/docs/quickstart-client-libraries#pubsub-client-libraries-go). Note that you won't need to install the Cloud SDK, as Watermill will take care of the administrative tasks (creating topics/subscriptions) with the default settings and proper permissions.
 
@@ -68,18 +70,16 @@ For development, you can use a Docker image with the emulator and the `PUBSUB_EM
 
 {{% load-snippet-partial file="src-link/_examples/pubsubs/googlecloud/main.go" first_line_contains="subscriber, err :=" last_line_contains="panic(err)" padding_after="1" %}}
 
-#### Publishing
+### Publishing
 
 {{% load-snippet-partial file="src-link/watermill-googlecloud/pkg/googlecloud/publisher.go" first_line_contains="// Publish" last_line_contains="func (p *Publisher) Publish" %}}
 
-#### Subscribing
+### Subscribing
 
 {{% load-snippet-partial file="src-link/watermill-googlecloud/pkg/googlecloud/subscriber.go" first_line_contains="// Subscribe " last_line_contains="func (s *Subscriber) Subscribe" %}}
 
-#### Marshaler
+### Marshaler
 
 Watermill's messages cannot be directly sent to Google Cloud Pub/Sub - they need to be marshaled. You can implement your marshaler or use the default implementation.
 
 {{% load-snippet-partial file="src-link/watermill-googlecloud/pkg/googlecloud/marshaler.go" first_line_contains="// Marshaler" last_line_contains="type DefaultMarshalerUnmarshaler " padding_after="0" %}}
-
-

docs/content/pubsubs/http.md

@@ -11,13 +11,13 @@ You can then post them to any Publisher. Here is an example with [sending HTTP m
 
 The HTTP publisher sends HTTP requests as specified in its configuration. Here is an example with [transforming Kafka messages into HTTP webhook requests](https://github.com/ThreeDotsLabs/watermill/tree/master/_examples/real-world-examples/sending-webhooks).
 
-### Installation
+## Installation
 
 ```bash
 go get github.com/ThreeDotsLabs/watermill-http/v2
 ```
 
-#### Characteristics
+### Characteristics
 
 | Feature | Implements | Note |
 | ------- | ---------- | ---- |
@@ -26,7 +26,7 @@ go get github.com/ThreeDotsLabs/watermill-http/v2
 | GuaranteedOrder | yes |  |
 | Persistent | no| |
 
-#### Subscriber configuration
+### Subscriber configuration
 
 Subscriber configuration is done via the config struct passed to the constructor:
 
@@ -35,20 +35,20 @@ Subscriber configuration is done via the config struct passed to the constructor
 You can use the `Router` config option to `SubscriberConfig` to pass your own `chi.Router` (see [chi](https://github.com/go-chi/chi)).
 This may be helpful if you'd like to add your own HTTP handlers (e.g. a health check endpoint).
 
-#### Publisher configuration
+### Publisher configuration
 
 Publisher configuration is done via the config struct passed to the constructor:
 
 {{% load-snippet-partial file="src-link/watermill-http/pkg/http/publisher.go" first_line_contains="type PublisherConfig struct" last_line_contains="}" %}}
 
-How the message topic and body translate into the URL, method, headers, and payload of the HTTP request is highly configurable through the use of `MarshalMessageFunc`. 
+How the message topic and body translate into the URL, method, headers, and payload of the HTTP request is highly configurable through the use of `MarshalMessageFunc`.
 Use the provided `DefaultMarshalMessageFunc` to send POST requests to a specific url:
 
 {{% load-snippet-partial file="src-link/watermill-http/pkg/http/publisher.go" first_line_contains="// MarshalMessageFunc" last_line_contains="return req, nil" padding_after="2" %}}
 
-You can pass your own `http.Client` to execute the requests or use Golang's default client. 
+You can pass your own `http.Client` to execute the requests or use Golang's default client.
 
-#### Running
+### Running
 
 To run HTTP subscriber you need to run `StartHTTPServer()`. It needs to be run after `Subscribe()`.
 
@@ -59,11 +59,11 @@ When using with the router, you should wait for the router to start.
 httpSubscriber.StartHTTPServer()
 ```
 
-#### Subscribing
+### Subscribing
 
 {{% load-snippet-partial file="src-link/watermill-http/pkg/http/subscriber.go" first_line_contains="// Subscribe adds" last_line_contains="func (s *Subscriber) Subscribe" %}}
 
-##### Custom HTTP status codes
+#### Custom HTTP status codes
 
 To specify a custom HTTP status code, which will returned as response, you can use following call during message handling: