From 6b527dfa618cfbb3b3730313e769e2fa84f43789 Mon Sep 17 00:00:00 2001
From: Zixuan James Li <p359101898@gmail.com>
Date: Tue, 16 Aug 2022 15:27:45 -0400
Subject: [PATCH] integrations: Add documentation for the event filtering
 system.

We create "event-filter-instruction.md" and add it to
"create-bot-construct-url.md". This allows the user to keep track of the
supported event types for most of the integrations that implement this
feature. Note that not all integrations use "create-bot-construct-url.md".

We also need to rename "function" to "view_function" to make this change
type-check.

This is relevant to #18392.

Signed-off-by: Zixuan James Li <p359101898@gmail.com>
---
 docs/documentation/integrations.md                    |  6 ++++++
 .../zerver/help/include/create-bot-construct-url.md   |  6 ++++++
 .../help/include/event-filtering-instruction.md       | 11 +++++++++++
 zerver/lib/integrations.py                            |  7 +++++--
 zerver/views/documentation.py                         |  5 +++++
 5 files changed, 33 insertions(+), 2 deletions(-)
 create mode 100644 templates/zerver/help/include/event-filtering-instruction.md

diff --git a/docs/documentation/integrations.md b/docs/documentation/integrations.md
index 90c868b4cd..00f8847b42 100644
--- a/docs/documentation/integrations.md
+++ b/docs/documentation/integrations.md
@@ -140,9 +140,15 @@ 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
 [codebase]: https://zulip.com/integrations/doc/codebase
 [beanstalk]: https://zulip.com/integrations/doc/beanstalk
+[front]: https://zulip.com/integrations/doc/front
 [integrations-file]: https://github.com/zulip/zulip/blob/main/zerver/lib/integrations.py
 
 ## Writing guidelines
diff --git a/templates/zerver/help/include/create-bot-construct-url.md b/templates/zerver/help/include/create-bot-construct-url.md
index b10671968c..c85f09545f 100644
--- a/templates/zerver/help/include/create-bot-construct-url.md
+++ b/templates/zerver/help/include/create-bot-construct-url.md
@@ -13,3 +13,9 @@ stream name you want the notifications sent to. If you do not specify a
 If you'd like this integration to always send to a specific topic,
 just include the (URL-encoded) topic as an additional parameter
 (E.g. for `your topic`, append `&topic=your%20topic` to the URL).
+
+{% if all_event_types is defined %}
+
+{!event-filtering-instruction.md!}
+
+{% endif %}
diff --git a/templates/zerver/help/include/event-filtering-instruction.md b/templates/zerver/help/include/event-filtering-instruction.md
new file mode 100644
index 0000000000..c1d52479d6
--- /dev/null
+++ b/templates/zerver/help/include/event-filtering-instruction.md
@@ -0,0 +1,11 @@
+To filter the events that trigger the notifications, you can append
+either `&only_events=["event_a","event_b"]` or `&exclude_events=["event_a","event_b"]`
+(or both, with different events) to the URL with an arbitrary number of supported events.
+
+Below are the events that {{ integration_display_name }} bot supports:
+
+{% for event_type in all_event_types %} `{{ event_type }}` {% endfor %}
+
+Note that you can also use UNIX-style wildcards like `*` to include
+multiple events. E.g., `test*` matches every event that starts with
+`test`.
diff --git a/zerver/lib/integrations.py b/zerver/lib/integrations.py
index 5c3ebb41ef..428f85ec0e 100644
--- a/zerver/lib/integrations.py
+++ b/zerver/lib/integrations.py
@@ -211,9 +211,12 @@ class WebhookIntegration(Integration):
             function = self.DEFAULT_FUNCTION_PATH.format(name=name)
 
         if isinstance(function, str):
-            function = import_string(function)
+            # We rename the imported function as view_function here to appease
+            # mypy, since it does not allow redefinition of variables with
+            # different types.
+            view_function = import_string(function)
 
-        self.function = function
+        self.function = view_function
 
         if url is None:
             url = self.DEFAULT_URL.format(name=name)
diff --git a/zerver/views/documentation.py b/zerver/views/documentation.py
index 4076e9ae20..96045a9087 100644
--- a/zerver/views/documentation.py
+++ b/zerver/views/documentation.py
@@ -307,6 +307,11 @@ def integration_doc(request: HttpRequest, integration_name: str = REQ()) -> Http
     context["recommended_stream_name"] = integration.stream_name
     if isinstance(integration, WebhookIntegration):
         context["integration_url"] = integration.url[3:]
+        if (
+            hasattr(integration.function, "_all_event_types")
+            and integration.function._all_event_types is not None
+        ):
+            context["all_event_types"] = integration.function._all_event_types
     if isinstance(integration, HubotIntegration):
         context["hubot_docs_url"] = integration.hubot_docs_url