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

@@ -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

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 %}

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`.

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)

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