docs: Adjust Eventing to new content guidelines (#315)

* adjust Eventing to new content guidelines * adjust sidebars * fix capitalization * Apply Natalia's suggestions Co-authored-by: Natalia Sitko <[email protected]> * remove "documentation overview", redundant with sidebar * prevent link check error * adjust diagrams to styleguide * adjust reconcile diagram * No more title case for Kyma dashboard --------- Co-authored-by: Natalia Sitko <[email protected]>
kyma-project · Dec 14, 2023 · 29e19fa · 29e19fa
1 parent f9a3f90
commit 29e19fa
Show file tree

Hide file tree

Showing 26 changed files with 164 additions and 191 deletions.
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Eventing Manager is a standard Kubernetes [operator](https://kubernetes.io/docs/
 
 This project is scaffolded using [Kubebuilder](https://book.kubebuilder.io), and all the Kubebuilder `makefile` helpers mentioned [here](https://book.kubebuilder.io/reference/makefile-helpers.html) can be used.
 
-## Get started
+## Get Started
 
 You need a Kubernetes cluster to run against. You can use [k3d](https://k3d.io/) to get a local cluster for testing, or run against a remote cluster.
 > **Note:** Your controller automatically uses the current context in your kubeconfig file, that is, whatever cluster `kubectl cluster-info` shows.
@@ -42,7 +42,7 @@ You need a Kubernetes cluster to run against. You can use [k3d](https://k3d.io/)
 - [kustomize](https://kustomize.io/)
 - Access to Kubernetes cluster ([k3d](https://k3d.io/) / k8s)
 
-### Run Eventing Manager locally
+### Run Eventing Manager Locally
 
 1. Install the CRDs into the cluster:
 
@@ -58,7 +58,7 @@ You need a Kubernetes cluster to run against. You can use [k3d](https://k3d.io/)
 
 > **NOTE:** You can also run this in one step with the command: `make install run`.
 
-### Run tests
+### Run Tests
 
 Run the unit and integration tests:
 
@@ -76,7 +76,7 @@ make generate-and-test
    make lint
    ```
 
-### Modify the API definitions
+### Modify the API Definitions
 
 If you are editing the API definitions, generate the manifests such as CRs or CRDs:
 
@@ -88,7 +88,7 @@ make manifests
 
 For more information, see the [Kubebuilder documentation](https://book.kubebuilder.io/introduction.html).
 
-### Build container images
+### Build Container Images
 
 Build and push your image to the location specified by `IMG`:
 
@@ -107,7 +107,7 @@ make docker-buildx IMG=<container-registry>/eventing-manager:<tag>
 You need a Kubernetes cluster to run against. You can use [k3d](https://k3d.io/) to get a local cluster for testing, or run against a remote cluster.
 > **Note:** Your controller automatically uses the current context in your kubeconfig file, that is, whatever cluster `kubectl cluster-info` shows.
 
-### Deploy on the cluster
+### Deploy on the Cluster
 
 1. Download Go packages:
 
@@ -133,14 +133,15 @@ You need a Kubernetes cluster to run against. You can use [k3d](https://k3d.io/)
    make deploy IMG=<container-registry>/eventing-manager:<tag>
    ```
 
-4. [Optional] Install `Eventing` Custom Resource:
+5. [Optional] Install `Eventing` Custom Resource:
 
    ```sh
    kubectl apply -f config/samples/default.yaml
    ```
 
-5. For EventMesh backend, if the Kyma Kubernetes cluster is managed by Gardener, then the Eventing Manager reads the cluster public domain from the ConfigMap **kube-system/shoot-info**.
+6. For EventMesh backend, if the Kyma Kubernetes cluster is managed by Gardener, then the Eventing Manager reads the cluster public domain from the ConfigMap **kube-system/shoot-info**.
    Otherwise, set the **spec.backend.config.domain** to the cluster public domain in the `eventing` custom resource; for example:
+
    ```yaml
    spec:
      backend:
@@ -167,7 +168,7 @@ To delete the CRDs from the cluster:
    make uninstall
    ```
 
-### Deploy Eventing Manager module with [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
+### Deploy Eventing Manager Module With [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
 
 1. Deploy the Lifecycle Manager to the Kubernetes cluster:
 
@@ -203,7 +204,7 @@ To delete the CRDs from the cluster:
      kubectl get -n kyma-system kyma
      ```
 
-### Uninstall Eventing Manager module with [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
+### Uninstall Eventing Manager Module With [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
 
 1. Delete Eventing custom resource (CR) from the Kubernetes cluster (if exists):
 

diff --git a/docs/assets/evnt-architecture.svg b/docs/assets/evnt-architecture.svg
diff --git a/docs/assets/evnt-pubsub.svg b/docs/assets/evnt-pubsub.svg
diff --git a/docs/assets/reconcileLoop.svg b/docs/assets/reconcileLoop.svg
diff --git a/docs/contributor/development.md b/docs/contributor/development.md
@@ -13,7 +13,8 @@ Projects created by Kubebuilder contain a Makefile with tooling that must be loc
 - [kustomize](https://kustomize.io/)
 - [golangci-lint](https://golangci-lint.run/)
 
-## Available commands
+## Available Commands
+
 Commands are available for easier development and installation of Eventing Manager.
 To find out which commands are available and for some more details about each command, run:
 

diff --git a/docs/contributor/governance.md b/docs/contributor/governance.md
@@ -3,7 +3,7 @@
 Some quality aspects are covered by automated verification, so you must execute tooling locally before a commit.
 This document guides you through the development flow.
 
-## Modifying the API definitions
+## Modifying the API Definitions
 
 This project uses the [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html) tool provided by [Kubebuilder](https://book.kubebuilder.io/).
 To modify the API definitions, you must adapt the ["marker comments"](https://book.kubebuilder.io/reference/markers.html) in the Go code.
@@ -13,17 +13,19 @@ The rules are written using the [Common Expression Language](https://github.com/
 For further information and examples, look to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) of validation rules and the CEL [language definition](https://github.com/google/cel-spec/blob/v0.10.0/doc/langdef.md).
 
 After the modifications, run the following command to generate the new manifests, such as custom resources (CRs) and CustomResourceDefinitions (CRDs):
+
 ```sh
 make manifests
 ```
 
 If changes to the `runtime.Object` interface were made, the `DeepCopy` functions must be updated as well.
 The generation is controlled by [Kubebuilder markers](https://book.kubebuilder.io/reference/markers/object.html?highlight=deep#objectdeepcopy).
+
 ```sh
 make generate
 ```
 
-## Source code linting
+## Source Code Linting
 
 The quality of this project is ensured by source code linting using [golangci-lint](https://golangci-lint.run/).
 

diff --git a/docs/contributor/installation.md b/docs/contributor/installation.md
@@ -1,14 +1,15 @@
-# Installation and uninstallation
+# Installation and Uninstallation
 
 There are several ways to install Eventing Manager.
 For development, you must run some make targets beforehand.
 For information about the prerequisites, refer to [Development](./development.md) and for a detailed guide to the development flow, visit [Governance](./governance.md).
 
-## Run the manager on a (k3d) cluster using a Docker image
+## Run the Manager on a (k3d) Cluster Using a Docker Image
 
 ### Installation
 
 1. Ensure you have a k3d cluster ready.
+
    ```sh
    k3d create cluster <clusterName>
    ```
@@ -57,9 +58,9 @@ This step depends on your desired backend: NATS or EventMesh.
       ```sh
       kubectl apply -f config/samples/default.yaml
       ```
-    
+
       The `spec.backend.type` needs to be set to `NATS`. You can configure the backend using the `NATS` related field in `spec.backend.config`.
-    
+
       ```sh
       spec:
         backend:
@@ -78,12 +79,12 @@ This step depends on your desired backend: NATS or EventMesh.
       ```sh
       kubectl apply -f config/samples/default_eventmesh.yaml
       ```
-   
+
       - `spec.backend.type`: set to `EventMesh`
       - `spec.backend.config.eventMeshSecret`: set it to the `<namespace>/<name>` where you applied the secret
       - `spec.backend.config.eventTypePrefix`: change to your desired value or leave as is
       - `spec.backend.config.domain`: set to the cluster public domain
-    
+
       If the Kyma Kubernetes cluster is managed by Gardener, Eventing Manager reads the cluster public domain automatically from the ConfigMap `kube-system/shoot-info`.
       Otherwise, you need to additionally set `spec.backend.config.domain` in the configuration. 
 
@@ -123,7 +124,7 @@ This step depends on your desired backend: NATS or EventMesh.
    make uninstall
    ```
 
-## Run Eventing Manager on a cluster using the Go runtime environment
+## Run Eventing Manager on a Cluster Using the Go Runtime Environment
 
 ### Installation
 
@@ -157,7 +158,7 @@ Remove the resources.
    make uninstall
    ```
 
-## Run Eventing Manager using Kyma's Lifecycle Manager
+## Run Eventing Manager Using Kyma’s Lifecycle Manager
 
 [Kyma's Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager) helps manage the lifecycle of each module in the cluster and can be used to install Eventing Manager.
 

diff --git a/docs/contributor/testing.md b/docs/contributor/testing.md
@@ -12,7 +12,7 @@ This document provides an overview of the testing activities used in this projec
 
 > **NOTE:** The validation and defaulting rules are tested within the integration tests.
 
-### Unit tests and env-tests
+### Unit Tests and Env-Tests
 
 To run the unit and integration tests, the following command must be executed. If necessary, the needed binaries for the integration tests are downloaded to `./bin`.
 Further information about integration tests can be found in the [Kubebuilder book](https://book.kubebuilder.io/reference/envtest.html).
@@ -27,7 +27,7 @@ If changes to the source code were made, or if this is your first time to execut
    make test
    ``` 
 
-### E2E tests
+### E2E Tests
 
 Because E2E tests need a Kubernetes cluster to run on, they are separate from the remaining tests.
 

diff --git a/docs/contributor/troubleshooting.md b/docs/contributor/troubleshooting.md
@@ -4,23 +4,23 @@ This document contains tips and tricks for common problems with Eventing Manager
 
 If you cannot find your issue described here, take a look at the [Eventing Troubleshooting](https://github.com/kyma-project/eventing-manager/blob/main/docs/user/troubleshooting/README.md)
 
-## Troubleshooting: Installing Eventing Manager using a Docker image
+## Troubleshooting: Installing Eventing Manager Using a Docker Image
 
-### Error while deploying Eventing Manager
+### Error While Deploying Eventing Manager
 
 **Symptom:** The `make deploy` step fails with the following error message:
 
 `Error from server (NotFound): error when creating "STDIN": namespaces kyma-system not found`
 
-**Cause:** The Namespace of the Deployment does not exist yet.
+**Cause:** The namespace of the Deployment does not exist yet.
 
-**Remedy:** Create the Namespace.
+**Remedy:** Create the namespace.
 
    ```sh
    kubectl create ns kyma-system
    ```
 
-## Reach out to us
+## Reach Out to Us
 
 If you encounter an issue or want to report a bug, please create a [GitHub issue](https://github.com/kyma-project/nats-manager/issues) with background information and
 steps on how to reproduce.

diff --git a/docs/user/01-manager.md b/docs/user/01-manager.md
@@ -1,8 +1,8 @@
-# Eventing manager
+# Eventing Manager
 
 This module ships Eventing Manager. Once this module is enabled, it provides the functionality to send and receive events.
 
-## Module lifecycle
+## Module Lifecycle
 
 Upon starting Eventing Manager, the controller (following the [Kubebuilder concept](https://book.kubebuilder.io/architecture.html)) creates, watches, and reconciles the following resources:
 
@@ -31,6 +31,6 @@ Eventing Manager supports switching between two different backends. [NATS](https
 
 For more information about the possible configuration of Eventing Manager using NATS or EventMesh backend, refer to the [backend configuration](02-configuration.md#reference).
 
-## Removing the module
+## Removing the Module
 
 The module cannot be removed as long as Subscription CRs exist. After the user cleans up all the subscriptions, the Eventing module can be removed. The module takes care of cleaning up all resources owned by it.
diff --git a/docs/user/README.md b/docs/user/README.md
@@ -1,6 +1,6 @@
-# Eventing module
+# Eventing Module
 
-This module ships Eventing Manager, which is a standard Kubernetes operator that observes the state of Eventing resources and reconciles them according to the desired state.
+The Eventing module ships Eventing Manager, which is a standard Kubernetes operator that observes the state of Eventing resources and reconciles them according to the desired state.
 
 With Kyma Eventing, you can focus on your business workflows and trigger them with events to implement asynchronous flows within Kyma. Generally, eventing consists of event producers (or publishers) and consumers (or subscribers) that send events to or receive events from an event processing backend.
 
@@ -12,7 +12,7 @@ Kyma Eventing uses the following technology:
 - [HTTP POST](https://www.w3schools.com/tags/ref_httpmethods.asp) requests to simplify sending and receiving events
 - Declarative [Subscription custom resource (CR)](./resources/evnt-cr-subscription.md) to subscribe to events
 
-## Kyma Eventing flow
+## Kyma Eventing Flow
 
 Kyma Eventing follows the PubSub messaging pattern: Kyma publishes messages to a messaging backend, which filters these messages and sends them to interested subscribers. Kyma does not send messages directly to the subscribers as shown below:
 
@@ -39,44 +39,3 @@ For more information, read [Eventing architecture](evnt-architecture.md).
 - **Delivery Guarantees**
   - `at least once` delivery: With NATS JetStream, Kyma ensures that for each event published, all the subscribers subscribed to that event receive the event at least once.
   - `max bytes and discard policy`: NATS JetStream uses these configurations to ensure that no messages are lost when the storage is almost full. By default, Kyma ensures that no new messages are accepted when the storage reaches 90% capacity.  
-
-## Documentation overview
-
-To learn more about how Eventing works, see:
-
-- [Eventing module](01-manager.md) - provides a general overview of the Eventing module
-- [Eventing module configuration](02-configuration.md) - contains information about configuring the Eventing module
-- [Eventing architecture](evnt-architecture.md) - describes how Eventing works and the main actors involved, such as Eventing Manager and Event Publisher Proxy.
-- [Event names](evnt-event-names.md) - contains information about event names and event name cleanup.
-- [Subscription CR](./resources/evnt-cr-subscription.md) - describes the Subscription custom resource, which you need to subscribe to events.
-- [CloudEvents](https://cloudevents.io/) - provides information about the CloudEvents specification used in Kyma.
-- [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream) - provides more information about the backend technology behind Eventing in Kyma. [Eventing Architecture](evnt-architecture.md#jet-stream) provides details on the functionalities and higher qualities of service on top of Core NATS.
-
-To learn more about technical details aimed at possible contributors, check out the following documents:
-- [Development](../contributor/development.md) - provides general information about the setup
-- [Governance](../contributor/governance.md) - provides information about the rules and norms of this project
-- [Installation guide](../contributor/installation.md) - contains information about the different ways to install the Eventing module
-- [Testing](../contributor/testing.md) - describes the test coverage of the project
-- [Troubleshooting](../contributor/troubleshooting.md) - provides general information about troubleshooting the module
-
-To perform tasks with Eventing, go through these tutorials:
-
-- [Tutorial: Trigger your workload with an event](https://kyma-project.io/#/02-get-started/04-trigger-workload-with-event) - shows how to deploy a Function and trigger it with an event.
-- [Tutorial: Create Subscription subscribing to multiple event types](tutorials/evnt-02-subs-with-multiple-filters.md) - shows how to subscribe to one or more event types using the Kyma Subscription.
-- [Tutorial: Event name cleanup in Subscriptions](tutorials/evnt-03-type-cleanup.md) - explains how Kyma Eventing filters out prohibited characters from event names.
-- [Tutorial: Changing Events Max-In-Flight in Subscriptions](tutorials/evnt-04-change-max-in-flight-in-sub.md) - shows how to set idle "in-flight messages" limit in Kyma Subscriptions.
-- [Tutorial: Publish legacy events using Kyma Eventing](tutorials/evnt-05-send-legacy-events.md) - demonstrates how to send legacy events using Kyma Eventing.
-
-To troubleshoot Eventing-related issues:
-
-- [Basic Eventing Troubleshooting](troubleshooting/evnt-01-eventing-troubleshooting.md)
-- [NATS JetStream Troubleshooting](troubleshooting/evnt-02-jetstream-troubleshooting.md)
-- [Event Type Collision](troubleshooting/evnt-03-type-collision.md)
-- [Eventing Backend Storage Full](troubleshooting/evnt-04-free-jetstream-storage.md)
-
-For other technical resources, check out these links on the Kyma GitHub repository:
-
-- [Eventing Helm chart](https://github.com/kyma-project/kyma/tree/main/resources/eventing)
-- [Event Publishing Proxy](https://github.com/kyma-project/kyma/tree/main/components/event-publisher-proxy)
-- [Eventing Manager](https://github.com/kyma-project/kyma/tree/main/components/eventing-controller)
-- [Eventing Metrics](evnt-eventing-metrics.md)
diff --git a/docs/user/_sidebar.md b/docs/user/_sidebar.md
@@ -1,21 +1,23 @@
-* [Home](/README.md)
-* [Eventing module](README.md)
-* [Module lifecycle](01-manager.md)
-* [Configuration](02-configuration.md)
-* [Eventing architecture](evnt-architecture.md)
-* [Event names](evnt-event-names.md)
-* [Eventing metrics](evnt-eventing-metrics.md)
+<!-- markdown-link-check-disable -->
+* [Back to Kyma Home](/)
+* [Eventing module](/eventing-manager/user/README.md)
+* [Module lifecycle](/eventing-manager/user/01-manager.md)
+* [Configuration](/eventing-manager/user/02-configuration.md)
+* [Eventing Architecture](/eventing-manager/user/evnt-architecture.md)
+* [Event Names](/eventing-manager/user/evnt-event-names.md)
+* [Eventing Metrics](/eventing-manager/user/evnt-eventing-metrics.md)
 * Tutorials
-  * [Prerequisites](./tutorials/evnt-01-prerequisites.md)
-  * [Create Subscription subscribing to multiple event types](./tutorials/evnt-02-subs-with-multiple-filters.md)
-  * [Event name cleanup in Subscriptions](./tutorials/evnt-03-type-cleanup.md)
-  * [Changing events max-in-flight in Subscriptions](./tutorials/evnt-04-change-max-in-flight-in-sub.md)
-  * [Publish legacy events using Kyma Eventing](./tutorials/evnt-05-send-legacy-events.md)
+  * [Prerequisites](/eventing-manager/user/tutorials/evnt-01-prerequisites.md)
+  * [Create Subscription Subscribing to Multiple Event Types](/eventing-manager/user/tutorials/evnt-02-subs-with-multiple-filters.md)
+  * [Event Name Cleanup in Subscriptions](/eventing-manager/user/tutorials/evnt-03-type-cleanup.md)
+  * [Changing Events Max-In-Flight in Subscriptions](/eventing-manager/user/tutorials/evnt-04-change-max-in-flight-in-sub.md)
+  * [Publish Legacy Events Using Kyma Eventing](/eventing-manager/user/tutorials/evnt-05-send-legacy-events.md)
 * Resources
-  * [Subscription CR](./resources/evnt-cr-subscription.md)
+  * [Subscription CR](/eventing-manager/user/resources/evnt-cr-subscription.md)
 * Troubleshooting
-  * [Kyma Eventing - basic diagnostics](./troubleshooting/evnt-01-eventing-troubleshooting.md)
-  * [NATS JetStream backend troubleshooting](./troubleshooting/evnt-02-jetstream-troubleshooting.md)
-  * [Subscriber receives irrelevant events](./troubleshooting/evnt-03-type-collision.md)
-  * [Eventing backend stopped receiving events due to full storage](./troubleshooting/evnt-04-free-jetstream-storage.md)
-  * [Published events are pending in the stream](./troubleshooting/evnt-05-fix-pending-messages.md)
+  * [Kyma Eventing - Basic Diagnostics](/eventing-manager/user/troubleshooting/evnt-01-eventing-troubleshooting.md)
+  * [NATS JetStream Backend Troubleshooting](/eventing-manager/user/troubleshooting/evnt-02-jetstream-troubleshooting.md)
+  * [Subscriber Receives Irrelevant Events](/eventing-manager/user/troubleshooting/evnt-03-type-collision.md)
+  * [Eventing Backend Stopped Receiving Events Due To Full Storage](/eventing-manager/user/troubleshooting/evnt-04-free-jetstream-storage.md)
+  * [Published Events Are Pending in the Stream](/eventing-manager/user/troubleshooting/evnt-05-fix-pending-messages.md)
+<!-- markdown-link-check-enable -->
diff --git a/docs/user/evnt-architecture.md b/docs/user/evnt-architecture.md
@@ -1,8 +1,8 @@
-# Eventing architecture
+# Eventing Architecture
 
 Eventing uses Event Publisher Proxy and Eventing Manager to connect to the default NATS JetStream backend. They work together to process and deliver events in Kyma.
 
-## Event processing and delivery
+## Event Processing and Delivery
 
 The event processing and delivery flow uses the NATS server to process events and send them to subscribers.
 This diagram explains the event flow in Kyma, from the moment an event source sends an event, to the point when the event triggers the Function.