paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-09 16:37:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add documentation guide for integrations and webhooks.

Browse Source
This commit is contained in:
Eeshan Garg
2017-06-30 02:35:29 -02:30
committed by showell
parent 2f054ef4c9
commit 9a992ec4c7
3 changed files with 276 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/index.rst
View File

@@ -78,6 +78,7 @@ Contents:
:caption: Developer tutorials
integration-guide
integration-docs-guide
webhook-walkthrough
new-feature-tutorial
writing-views

273
docs/integration-docs-guide.md Normal file
View File

@@ -0,0 +1,273 @@
# 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](#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](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/<integration_name>.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/<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][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

53
docs/integration-guide.md
View File

@@ -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/<integration_name>.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/<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.
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).