integrations: Restructure documentation pages.

Restructures the integration documentation pages to use a style
that's more similar to the help center documentation, with an
instruction block for setting up the integration, and sections
for additional configuration information and related documentation
links.

Updates the doc pages for the airbrake, azuredevops and gitlab
integrations as examples of the updated style.

Also updates the URL specification section of the incoming webhook
overview in the API documentation so that the documented URL
parameters can be linked to directly in the integration doc pages.

Co-authored-by: Alya Abbott <alya@zulip.com>

api_docs/incoming-webhooks-overview.md

@@ -189,9 +189,17 @@ Parameters accepted in the URL include:
   [URL-encoded][url-encoder]. By default the integration will have a
   topic configured for stream messages.
 
-* `only_events`, `exclude_events`: Some incoming webhook integrations
-  support these parameters to filter which events will trigger a
-  notification. For details, see the integration's [integration
+* `only_events`, `exclude_events`: Some incoming webhook integrations support
+  these parameters to filter which events will trigger a notification. 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. You can use UNIX-style
+  wildcards like `*` to include multiple events. For example, `test*` matches
+  every event that starts with `test`.
+
+    !!! tip ""
+
+        For a list of supported events, see the integration's [integration
         documentation](/integrations) page.
 
 [browse-streams]: /help/browse-and-subscribe-to-streams

templates/zerver/integrations/include/congrats.md

@@ -1,3 +1,2 @@
-**Congratulations! You're done!**
-
-Your {{ integration_display_name }} notifications may look like:
+You're done! Your {{ integration_display_name }} notifications may look like
+this:

templates/zerver/integrations/include/event-filtering-additional-feature.md

@@ -0,0 +1,8 @@
+### Filtering incoming events
+
+The {{ integration_display_name }} integration supports filtering for
+the following events:
+
+{% set comma = joiner(", ") %}
+
+{% for event_type in all_event_types -%} {{- comma() -}} `{{ event_type }}` {%- endfor %}

templates/zerver/integrations/include/generate-webhook-url-basic.md

@@ -0,0 +1,4 @@
+[Generate the URL][generate-url] for your {{ integration_display_name }}
+integration.
+
+[generate-url]: /help/generate-integration-url

templates/zerver/integrations/include/git-branches-additional-feature.md

@@ -0,0 +1,3 @@
+* You can limit the branches you receive notifications for by
+  specifying them in a comma-separated list appended to the generated
+  URL, e.g. `&branches=main,development`.

templates/zerver/integrations/include/webhooks-url-specification.md

@@ -0,0 +1,3 @@
+* [Webhook URLs specification][incoming-webhook-urls]
+
+[incoming-webhook-urls]: /api/incoming-webhooks-overview#urls

zerver/webhooks/airbrake/doc.md

@@ -1,17 +1,27 @@
+# Zulip Airbrake integration
+
 Get Zulip notifications for your Airbrake bug tracker!
 
+{start_tabs}
+
 1. {!create-stream.md!}
 
 1. {!create-an-incoming-webhook.md!}
 
-1. {!generate-integration-url.md!}
+1. {!generate-webhook-url-basic.md!}
 
 1. Go to your project's settings on the Airbrake site. Click on the
    **Integration** section, and select **Webhook**.
 
-1. Enter the URL constructed above, and check **Enabled**.
+1. Enter the URL you generated, and check **Enabled**.
    Click **Save**.
 
+{end_tabs}
+
 {!congrats.md!}
 
 ![](/static/images/integrations/airbrake/001.png)
+
+### Related documentation
+
+{!webhooks-url-specification.md!}

zerver/webhooks/azuredevops/doc.md

@@ -1,30 +1,43 @@
-Get Azure Devops notifications in Zulip!
+# Zulip Azure DevOps integration
+
+Get Azure DevOps notifications in Zulip!
+
+{start_tabs}
 
 1. {!create-stream.md!}
 
 1. {!create-an-incoming-webhook.md!}
 
-1. {!generate-integration-url.md!}
+1. {!generate-webhook-url-basic.md!}
 
-    {!git-webhook-url-with-branches.md!}
+1. Go to your project on Azure DevOps, click on the **Project
+   settings** in the bottom left corner and select **Service
+   hooks**. Click on **Create subscription**, select
+   **Web hooks**, and click **Next**.
 
-1. Go to your project on Azure DevOps and click on the **Project
-   settings** in the bottom left corner. Select **Service
-   hooks**. Click on **Create subscription**. Select **Web hooks** and
-   then **Next**.
+1. Select the [events](#filtering-incoming-events) you would like to receive
+   notifications for, and click **Next**.
 
-1. Select the events you would like to receive notifications for and
-   then click **Next**. This integration supports the following
-   events:
-    * Code pushed
-    * Pull request created
-    * Pull request updated
-    * Pull request merge attempted
-
-1. Set **URL** to the URL constructed above. Ensure that **Resource
+1. Set **URL** to the URL you generated. Ensure that **Resource
    details to send** and **Detailed messages to send** are set to
    **All**. Click **Finish**.
 
+{end_tabs}
+
 {!congrats.md!}
 
 ![](/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!}
+
+### Related documentation
+
+{!webhooks-url-specification.md!}

zerver/webhooks/gitlab/doc.md

@@ -1,34 +1,52 @@
+# Zulip GitLab integration
+
 Receive GitLab notifications in Zulip!
 
+{start_tabs}
+
 1. {!create-stream.md!}
 
 1. {!create-an-incoming-webhook.md!}
 
-1. {!generate-integration-url.md!}
-
-    By default, the Zulip topics for merge requests will contain the
-    title of the GitLab merge request.  You can change the topic format to
-    just contain the merge request ID by adding
-    `&use_merge_request_title=false` at the end of the URL.
-
-    {!git-webhook-url-with-branches.md!}
+1. {!generate-webhook-url-basic.md!}
 
 1. Go to your repository on GitLab and click **Settings** on the left
    sidebar.  Click on **Integrations**.
 
-1. Set **URL** to the URL constructed above. Select the events you
-   you would like to receive notifications for, and click
-   **Add Webhook**.
+1. Set **URL** to the URL you generated. Select the
+   [events](#filtering-incoming-events) you you would like to receive
+   notifications for, and click **Add Webhook**.
 
-{!congrats.md!}
+!!! warn ""
 
-![](/static/images/integrations/gitlab/001.png)
-
-!!! tip ""
-
-    If your GitLab server and your Zulip server are on a local network
+    **Note**: If your GitLab server and your Zulip server are on a local network
     together, and you're running GitLab 10.5 or newer, you may need to enable
     GitLab's "Allow requests to the local network from hooks and
     services" setting (by default, recent GitLab versions refuse to post
     webhook events to servers on the local network).  You can find this
     setting near the bottom of the GitLab "Settings" page in the "Admin area".
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/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
+  of the GitLab merge request. You can change the topic format to just
+  contain the merge request ID by adding `&use_merge_request_title=false`
+  to the generated URL.
+
+{!git-branches-additional-feature.md!}
+
+### Related documentation
+
+{!webhooks-url-specification.md!}