zulip/templates/zerver/api/integration-docs-guide.md

Documenting an integration

Every Zulip integration must be documented in zerver/webhooks/mywebhook/doc.md (or templates/zerver/integrations/<integration_name>.md, for non-webhook integrations).

Usually, this involves a few steps:

• Add text explaining all of the steps required to setup the integration, including what URLs to use, etc. If there are any screens in the product involved, take a few screenshots with the input fields filled out with sample values in order to make the instructions really easy to follow. For the screenshots, use a bot with a name like "GitHub Bot", and an email address for the bot like github-bot@zulip.example.com. Zulip's pre-defined Markdown macros can be used for some of these steps. See Markdown macros for further details.

• Make sure you've added your integration to zerver/lib/integrations.py; this results in your integration appearing on the /integrations page.

• You'll need to add a SVG graphic of your integration's logo under the static/images/integrations/logos/<name>.svg, where <name> is the name of the integration, all in lower case; you can usually find them in the product branding or press page. Make sure to optimize the SVG graphic by running svgo -f path-to-file.

  If you cannot find a SVG graphic of the logo, please find and include a PNG image of the logo instead.

• Finally, generate a message sent by the integration and take a screenshot of the message to provide an example message in the documentation. If your new integration is a webhook integration, you can generate such a message from your test fixtures using send_webhook_fixture_message:

  ./manage.py send_webhook_fixture_message \
       --fixture=zerver/webhooks/pingdom/fixtures/imap_down_to_up.json \
       '--url=/api/v1/external/pingdom?stream=stream_name&api_key=api_key'
  

  When generating the screenshot of a sample message, give your test bot a nice name like "GitHub Bot", use the project's logo as the bot's avatar, and take the screenshots showing the stream/topic bar for the message, not just the message body.

Markdown macros

Macros are elements in the format of {!macro.md!} that insert common phrases and steps at the location of the macros. Macros help eliminate repeated content in our documentation.

The source for macros is the Markdown files under templates/zerver/help/include in the main Zulip server repository. If you find multiple instances of particular content in the documentation, you can always create a new macro by adding a new file to that folder.

Here are a few common macros used to document Zulip's integrations:

{!create-stream.md!} macro

• About: Recommends that users create a dedicated stream for a given integration. Usually the first step in setting up an integration or webhook.

• Contents: See source. Note: {{ integration_display_name }} is replaced by Integration.display_name and {{ recommended_stream_name }} is replaced by Integration.stream_name.

• Example usage:

  {!create-stream.md!}
  

• Example rendering:

  First, create the stream you would like to use for GitLab notifications,
  and subscribe all interested parties to this stream. We recommend the
  name gitlab.
  
  The integration will use the default stream gitlab if no stream is
  supplied in the URL; you still need to create the stream even if you
  are using this default.
  

{!create-bot-construct-url.md!} macro

• About: Instructs users to create a bot for a given integration and construct a webhook URL using the bot API key and stream name. The URL is generated automatically for every webhook by using attributes in the WebhookIntegration class.

• Contents: See source. Note: If special configuration is required to set up the URL and you can't use this macro, be sure to use the {{ api_url }} template variable, so that your integration documentation will provide the correct URL for whatever server it is deployed on. If special configuration is required to set the SITE variable, you should document that too.

• Example usage:

  {!create-bot-construct-url.md!}
  

  Usually used right after {!create-stream!}.

• Example rendering:

  Next, on your Zulip settings page, create a bot for GitLab. Construct
  the URL for the GitLab bot using the bot API key and stream name:
  
  https://yourZulipDomain.zulipchat.com/api/v1/external/gitlab?api_key=abcdefgh&stream=gitlab
  
  Modify the parameters of the URL above, where api_key is the API key of
  your Zulip bot, and stream is the stream name you want the notifications
  sent to.
  

{!append-stream-name.md!} macro

• About: Recommends appending &stream=stream_name to a URL in cases where supplying a stream name in the URL is optional.

• Contents: See source.

• Example usage: Usually used right after {!create-bot-construct-url.md!}.

  {!append-stream-name.md!}
  

• Example rendering:

  To specify the stream, you must explicitly append
  `&stream=stream_name` to the end of the above URL, where
  `stream_name` is the stream you want the notifications sent to.
  

{!append-topic.md!} macro

• About: Recommends appending &topic=my_topic to a URL to supply a custom topic for webhook notification messages.

• Contents: See source.

• Example usage: Usually used right after {!create-bot-construct-url.md!}.

  {!append-topic.md!}
  

• Example rendering:

  To change the topic used by the bot, simply append `&topic=name`
  to the end of the above URL, where `name` is your topic.
  

{!congrats.md!} macro

• About: Inserts congratulatory lines signifying the successful setup of a given integration.

• Contents: See source.

• Example usage: Usually used at the end of the documentation, right before the sample message screenshot.

  {!congrats.md!}
  

• Example rendering:

  **Congratulations! You're done!**
  
  Your WebhookName notifications may look like:
  

{!download-python-bindings.md!} macro

• About: Links to Zulip's API page to download and install Zulip's API bindings.

• Contents: See source.

• Example usage: Currently mostly used in non-webhook integrations docs under templates/zerver/integrations/<integration_name>.md.

  {!download-python-bindings.md!}
  

• Example rendering:

  Download and install our [Python bindings and example scripts](/api)
  on the server where the IntegrationName bot will live.
  

{!change-zulip-config-file.md!} macro

• About: Instructs users to create a bot and specify said bot's credentials in the config file for a given non-webhook integration.

• Contents: See source.

• Example usage: Usually used in non-webhook integration docs under templates/zerver/integrations/<integration_name>.md.

  {!change-zulip-config-file.md!}
  

• Example rendering:

  On your Zulip settings page, create a bot for Codebase.
  
  Next, open `integrations/codebase/zulip_codebase_config.py` with your
  favorite editor, and change the following lines to specify the email
  address and API key for your Codebase bot:
  
      ZULIP_USER = "codebase-bot@example.com"
      ZULIP_API_KEY = "0123456789abcdef0123456789abcdef"
      ZULIP_SITE = "http://localhost:9991/api"
  

{!git-append-branches.md!} and {!git-webhook-url-with-branches.md!}

• About: These two macros explain how to specify a list of branches in the webhook URL to filter notifications in our Git-related webhooks.

• Contents: See git-append-branches and git-webhook-url-with-branches.

• Example usage: Used exclusively in Git integrations.

  {!git-append-branches.md!}
  {!git-webhook-url-with-branches.md!}
  

Other useful macros

• {!webhook-url.md!} - Used internally by {!create-bot-construct-url.md!} to generate the webhook URL. See source.

• {!zulip-config.md!} - Used internally by {!change-zulip-config-file.md!} to specify the lines in the config file for a non-webhook integration. See source.

• {!webhook-url-with-bot-email.md!} - Used in certain non-webhook integrations to generate URLs of the form (see source):

  https://bot_email:bot_api_key@yourZulipDomain.zulipchat.com/api/v1/external/beanstalk
  

  A good example is Zulip's Beanstalk integration