From 9a992ec4c70d46b5aad6c21acfea8fd8441a8f15 Mon Sep 17 00:00:00 2001 From: Eeshan Garg Date: Fri, 30 Jun 2017 02:35:29 -0230 Subject: [PATCH] docs: Add documentation guide for integrations and webhooks. --- docs/index.rst | 1 + docs/integration-docs-guide.md | 273 +++++++++++++++++++++++++++++++++ docs/integration-guide.md | 53 +------ 3 files changed, 276 insertions(+), 51 deletions(-) create mode 100644 docs/integration-docs-guide.md diff --git a/docs/index.rst b/docs/index.rst index f1749f1564..1d23d0078d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -78,6 +78,7 @@ Contents: :caption: Developer tutorials integration-guide + integration-docs-guide webhook-walkthrough new-feature-tutorial writing-views diff --git a/docs/integration-docs-guide.md b/docs/integration-docs-guide.md new file mode 100644 index 0000000000..18ef31ac48 --- /dev/null +++ b/docs/integration-docs-guide.md @@ -0,0 +1,273 @@ +# Documenting an integration + +Every Zulip integration must be documented in +`zerver/webhooks/mywebhook/doc.md` (or +`templates/zerver/integrations/.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](#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/.svg`, where `` 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](https://github.com/zulip/zulip). 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][1]. + **Note:** `{{ integration_display_name }}` is replaced by + [Integration.display_name][2] and `{{ recommended_stream_name }}` + is replaced by [Integration.stream_name][3]. + +* **Example usage:** + ``` + {!create-stream.md!} + ``` + +* **Example rendering:** + ``` text + 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][4] class. + +* **Contents:** See [source][5]. **Note:** If special configuration is + required to set up the URL and you can't use this macro, be sure to use the + `{{ external_api_uri }}` 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, inside an `{% if + api_site_required %}` check. + +* **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][6]. + +* **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][7]. + +* **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][8]. + +* **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](https://zulipchat.com/api/) to download + and install Zulip's API bindings. + +* **Contents:** See [source][9]. + +* **Example usage:** Currently mostly used in non-webhook integrations docs + under `templates/zerver/integrations/.md`. + ``` + {!download-python-bindings.md!} + ``` + +* **Example rendering:** + ``` text + 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][10]. + +* **Example usage:** Usually used in non-webhook integration docs under + `templates/zerver/integrations/.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][12] and + [git-webhook-url-with-branches][13]. + +* **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][11]. + +* `{!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][15]. + +* `{!webhook-url-with-bot-email.md!}` - Used in certain non-webhook integrations + to generate URLs of the form (see [source][14]): + ``` + https://bot_email:bot_api_key@yourZulipDomain.zulipchat.com/api/v1/external/beanstalk + ``` + A good example is + [Zulip's Beanstalk integration](https://zulipchat.com/integrations/#beanstalk) + +[1]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/create-stream.md +[2]: https://github.com/zulip/zulip/blob/708f3a4bb19c8e823c9ea1e577d360ac4229b199/zerver/lib/integrations.py#L51 +[3]: https://github.com/zulip/zulip/blob/708f3a4bb19c8e823c9ea1e577d360ac4229b199/zerver/lib/integrations.py#L55 +[4]: https://github.com/zulip/zulip/blob/708f3a4bb19c8e823c9ea1e577d360ac4229b199/zerver/lib/integrations.py#L78 +[5]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/create-bot-construct-url.md +[6]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/append-stream-name.md +[7]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/append-topic.md +[8]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/congrats.md +[9]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/download-python-bindings.md +[10]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/change-zulip-config-file.md +[11]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/webhook-url.md +[12]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/git-append-branches.md +[13]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/git-webhook-url-with-branches.md +[14]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/webhook-url-with-bot-email.md +[15]: https://github.com/zulip/zulip/blob/master/templates/zerver/help/include/zulip-config.md diff --git a/docs/integration-guide.md b/docs/integration-guide.md index 9e27ec9a4c..23ef3519ec 100644 --- a/docs/integration-guide.md +++ b/docs/integration-guide.md @@ -205,54 +205,5 @@ ZulipMobile/0.5.4 (Android; 4.2; maguro) ## Documenting your integration -Every Zulip integration must be documented in -`zerver/webhooks/mywebhook/doc.html` (or -`templates/zerver/integrations/.html`, 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", an email address for the bot like - `github-bot@zulip.example.com`, and an obviously fake API key like - `abcdef123456790`. - -* 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/.svg`, where `` 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. - -When writing documentation for your integration, be sure to use the -`{{ external_api_uri }}` 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, inside an `{% if -api_site_required %}` check. +See +[our guide for writing integration documentation](integration-docs-guide.html).