From 7e7e6b7ba9a628f485cd97e4f6b5680ecb03fc9a Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Mon, 8 Jul 2024 14:03:25 +0200 Subject: [PATCH] integration-docs: Clarify use of event-filtering-additional-feature. Using an if block when {!event-filtering-additional-feature.md!} is used implied that we plan to have this in all webhook doc .md files. But, it actually makes sense to only use this macro when the webhook integration actually supports event filtering. --- docs/documentation/integrations.md | 13 ++++++++----- zerver/webhooks/azuredevops/doc.md | 4 ---- zerver/webhooks/basecamp/doc.md | 4 ---- zerver/webhooks/bitbucket2/doc.md | 4 ---- zerver/webhooks/bitbucket3/doc.md | 4 ---- zerver/webhooks/circleci/doc.md | 4 ---- zerver/webhooks/clubhouse/doc.md | 4 ---- zerver/webhooks/freshping/doc.md | 4 ---- zerver/webhooks/freshstatus/doc.md | 4 ---- zerver/webhooks/front/doc.md | 4 ---- zerver/webhooks/gitlab/doc.md | 4 ---- zerver/webhooks/grafana/doc.md | 4 ---- 12 files changed, 8 insertions(+), 49 deletions(-) diff --git a/docs/documentation/integrations.md b/docs/documentation/integrations.md index 9c45bcceec..5c8a05234c 100644 --- a/docs/documentation/integrations.md +++ b/docs/documentation/integrations.md @@ -118,6 +118,13 @@ Here are a few common macros used to document Zulip's integrations: For an example rendering, see the end of [the docs for Zulip's GitHub integration][github-integration]. +- `{!event-filtering-additional-feature.md!}` macro - If a webhook integration + supports event filtering, then this adds a section with the specific + events that can be filtered for the integration. Should be included in + the documentation if `all_event_types` is set in the webhook integration + view. For an example see, the **Filtering incoming events** section in + [Zulip's GitLab integration][gitlab]. + - `{!download-python-bindings.md!}` macro - Links to Zulip's [API page](https://zulip.com/api/) to download and install Zulip's API bindings. This macro is usually used in non-webhook integration docs under @@ -151,17 +158,13 @@ Here are a few common macros used to document Zulip's integrations: For an example rendering, see [Zulip's Beanstalk integration](https://zulip.com/integrations/doc/beanstalk). -- `{!event-filtering-instructions}` macro - Instructs user to use the event - filtering feature and shows a list of event types that the integration supports. - For an example rendering, see the last 4 paragraphs of **Step 2** in - [the docs for Zulip's Front integration][front]. - [github-integration]: https://zulip.com/integrations/doc/github [zendesk]: https://zulip.com/integrations/doc/zendesk [matrix]: https://zulip.com/integrations/doc/matrix#configure-the-bridge [codebase]: https://zulip.com/integrations/doc/codebase [beanstalk]: https://zulip.com/integrations/doc/beanstalk [front]: https://zulip.com/integrations/doc/front +[gitlab]: https://zulip.com/integrations/doc/gitlab [integrations-file]: https://github.com/zulip/zulip/blob/main/zerver/lib/integrations.py ## Writing guidelines diff --git a/zerver/webhooks/azuredevops/doc.md b/zerver/webhooks/azuredevops/doc.md index b48474dd81..5cfbe8dc54 100644 --- a/zerver/webhooks/azuredevops/doc.md +++ b/zerver/webhooks/azuredevops/doc.md @@ -28,12 +28,8 @@ Get Azure DevOps notifications in Zulip! ![](/static/images/integrations/azuredevops/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Configuration options {!git-branches-additional-feature.md!} diff --git a/zerver/webhooks/basecamp/doc.md b/zerver/webhooks/basecamp/doc.md index 7c8fc78799..c57142ea00 100644 --- a/zerver/webhooks/basecamp/doc.md +++ b/zerver/webhooks/basecamp/doc.md @@ -25,12 +25,8 @@ Receive notifications about Basecamp events in Zulip! ![](/static/images/integrations/basecamp/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Related documentation {!webhooks-url-specification.md!} diff --git a/zerver/webhooks/bitbucket2/doc.md b/zerver/webhooks/bitbucket2/doc.md index 213cbf4b93..bcea670df2 100644 --- a/zerver/webhooks/bitbucket2/doc.md +++ b/zerver/webhooks/bitbucket2/doc.md @@ -30,12 +30,8 @@ Bitbucket Server click [here](./bitbucket3). ![](/static/images/integrations/bitbucket/003.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Configuration options {!git-branches-additional-feature.md!} diff --git a/zerver/webhooks/bitbucket3/doc.md b/zerver/webhooks/bitbucket3/doc.md index 08025cdb7e..a2b8bbaaf9 100644 --- a/zerver/webhooks/bitbucket3/doc.md +++ b/zerver/webhooks/bitbucket3/doc.md @@ -30,12 +30,8 @@ Bitbucket Cloud (SAAS service) click [here](./bitbucket2). ![](/static/images/integrations/bitbucket/004.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Configuration options {!git-branches-additional-feature.md!} diff --git a/zerver/webhooks/circleci/doc.md b/zerver/webhooks/circleci/doc.md index 4a6d0a6858..f883533ec2 100644 --- a/zerver/webhooks/circleci/doc.md +++ b/zerver/webhooks/circleci/doc.md @@ -27,12 +27,8 @@ CircleCI with GitHub, BitBucket and GitLab. ![](/static/images/integrations/circleci/001.png) ![](/static/images/integrations/circleci/002.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Related documentation {!webhooks-url-specification.md!} diff --git a/zerver/webhooks/clubhouse/doc.md b/zerver/webhooks/clubhouse/doc.md index 4a3f75088c..691e980ed3 100644 --- a/zerver/webhooks/clubhouse/doc.md +++ b/zerver/webhooks/clubhouse/doc.md @@ -23,12 +23,8 @@ Get Zulip notifications for your Clubhouse Stories and Epics! ![](/static/images/integrations/clubhouse/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Related documentation {!webhooks-url-specification.md!} diff --git a/zerver/webhooks/freshping/doc.md b/zerver/webhooks/freshping/doc.md index 70e2d760a2..eda41b4398 100644 --- a/zerver/webhooks/freshping/doc.md +++ b/zerver/webhooks/freshping/doc.md @@ -23,12 +23,8 @@ Receive Freshping notifications in Zulip! ![](/static/images/integrations/freshping/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Related documentation {!webhooks-url-specification.md!} diff --git a/zerver/webhooks/freshstatus/doc.md b/zerver/webhooks/freshstatus/doc.md index 11d66897dd..dde39acb3b 100644 --- a/zerver/webhooks/freshstatus/doc.md +++ b/zerver/webhooks/freshstatus/doc.md @@ -86,12 +86,8 @@ Receive Freshstatus notifications in Zulip! ![](/static/images/integrations/freshstatus/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Related documentation {!webhooks-url-specification.md!} diff --git a/zerver/webhooks/front/doc.md b/zerver/webhooks/front/doc.md index 90e2e8ece8..d73b4897ea 100644 --- a/zerver/webhooks/front/doc.md +++ b/zerver/webhooks/front/doc.md @@ -32,12 +32,8 @@ to receive Front notifications without leaving Zulip! ![](/static/images/integrations/front/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Related documentation {!webhooks-url-specification.md!} diff --git a/zerver/webhooks/gitlab/doc.md b/zerver/webhooks/gitlab/doc.md index 7466457894..c9ecbfeb21 100644 --- a/zerver/webhooks/gitlab/doc.md +++ b/zerver/webhooks/gitlab/doc.md @@ -32,12 +32,8 @@ Receive GitLab notifications in Zulip! ![](/static/images/integrations/gitlab/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Configuration options * By default, the Zulip topics for merge requests will contain the title diff --git a/zerver/webhooks/grafana/doc.md b/zerver/webhooks/grafana/doc.md index d7ea87e1ed..29fe92af4b 100644 --- a/zerver/webhooks/grafana/doc.md +++ b/zerver/webhooks/grafana/doc.md @@ -68,12 +68,8 @@ See your Grafana dashboard alerts in Zulip! ![](/static/images/integrations/grafana/001.png) -{% if all_event_types is defined %} - {!event-filtering-additional-feature.md!} -{% endif %} - ### Related documentation {!webhooks-url-specification.md!}