From 7c5340dc213922e057fd35ceb95b4d273fbd36df Mon Sep 17 00:00:00 2001 From: Adam Birds Date: Fri, 7 May 2021 00:55:31 +0000 Subject: [PATCH] docs: Update how to build an incoming webhook docs. Update docs on how to build an incoming webhook integration to be more accurate on exactly what is needed at this point in time as they were quite out of date. --- .../zerver/api/incoming-webhooks-overview.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/templates/zerver/api/incoming-webhooks-overview.md b/templates/zerver/api/incoming-webhooks-overview.md index beaee929a7..5d77640dfc 100644 --- a/templates/zerver/api/incoming-webhooks-overview.md +++ b/templates/zerver/api/incoming-webhooks-overview.md @@ -9,7 +9,7 @@ Zulip: or cases where the third-party tool wants to control the formatting of the messages in Zulip. * Use one of our supported [integration - frameworks](/integrations/doc/meta-integration), such as the + frameworks](/integrations/meta-integration), such as the [Slack-compatible incoming webhook](/integrations/doc/slack_incoming), [Zapier integration](/integrations/docs/zapier), or [IFTTT integration](/integrations/doc/ifttt). @@ -90,13 +90,19 @@ below are for a webhook named `MyWebHook`. used by tests. Add one fixture file per type of message supported by your integration. * `zerver/webhooks/mywebhook/tests.py`: Tests for your webbook. -* `zerver/webhooks/mywebhook/doc.html`: End-user documentation explaining +* `zerver/webhooks/mywebhook/doc.md`: End-user documentation explaining how to add the integration. * `static/images/integrations/logos/mywebhook.svg`: A square logo for the platform/server/product you are integrating. Used on the documentation pages as well as the sender's avatar for messages sent by the integration. * `static/images/integrations/mywebbook/001.svg`: A screenshot of a message - sent by the integration, used on the documentation page. + sent by the integration, used on the documentation page. This can be + generated by running `tools/generate-integration-docs-screenshot --integration mywebhook`. +* `static/images/integrations/bot_avatars/mywebhook.png`: A square logo for the + platform/server/product you are integrating which is used to create the avatar + for generating screenshots with. This can be generated automatically from + `static/images/integrations/logos/mywebhook.svg` by running + `tools/setup/generate_integration_bots_avatars.py`. ### Files that need to be updated @@ -104,7 +110,10 @@ below are for a webhook named `MyWebHook`. `WEBHOOK_INTEGRATIONS`. This will automatically register a URL for the incoming webhook of the form `api/v1/external/mywebhook` and associate it with the function called `api_mywebhook_webhook` in - `zerver/webhooks/mywebhook/view.py`. + `zerver/webhooks/mywebhook/view.py`. Also add your integration to + `DOC_SCREENSHOT_CONFIG`. This will allow you to automatically generate + a screenshot for the documentation by running + `tools/generate-integration-docs-screenshot --integration mywebhook`. ## Common Helpers