paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-28 10:33:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update to advise on preferred indented macros in integration docs.

Browse Source 
I have update the integrations documentation to advise on the correct
macros to use now we prefer the indented macros.
This commit is contained in:
Adam Birds
2021-04-16 22:06:16 +00:00
committed by Tim Abbott
parent ccfcc186ad
commit fa22fe54b0
1 changed files with 5 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/documentation/integrations.md
View File

@@ -74,7 +74,7 @@ Here are a few common macros used to document Zulip's integrations:
integration or incoming webhook. For an example rendering, see **Step 1** of
[the docs for Zulip's GitHub integration][GitHub].
* `{!create-bot-construct-url.md!}` macro - Instructs users to create a bot
* `{!create-bot-construct-url-indented.md!}` macro - 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 incoming webhook
by using attributes in the `WebhookIntegration` class in
@@ -92,12 +92,12 @@ Here are a few common macros used to document Zulip's integrations:
* `{!append-stream-name.md!}` macro - Recommends appending `&stream=stream_name`
to a URL in cases where supplying a stream name in the URL is optional.
Supplying a stream name is optional for most Zulip integrations. If you use
`{!create-bot-construct-url.md!}`, this macro need not be used.
`{!create-bot-construct-url-indented.md!}`, this macro need not be used.
* `{!append-topic.md!}` macro - Recommends appending `&topic=my_topic` to a URL
to supply a custom topic for webhook notification messages. Supplying a custom
topic is optional for most Zulip integrations. If you use
`{!create-bot-construct-url.md!}`, this macro need not be used.
`{!create-bot-construct-url-indented.md!}`, this macro need not be used.
* `{!congrats.md!}` macro - Inserts congratulatory lines signifying the
successful setup of a given integration. This macro is usually used at
@@ -125,7 +125,7 @@ Here are a few common macros used to document Zulip's integrations:
see the last paragraph of **Step 2** in
[the docs for Zulip's GitHub integration][GitHub].
* `{!webhook-url.md!}` - Used internally by `{!create-bot-construct-url.md!}`
* `{!webhook-url.md!}` - Used internally by `{!create-bot-construct-url-indented.md!}`
to generate the webhook URL.
* `{!zulip-config.md!}` - Used internally by `{!change-zulip-config-file.md!}`
@@ -201,7 +201,7 @@ A typical doc will then have the following steps.
##### "Create the bot" step
- Typically, use the `create-bot-construct-url` macro.
- Typically, use the `create-bot-construct-url-indented` macro.
- [Existing macros](#markdown-macros) should be used for this if they exist, but if the macro
defaults don’t work, it may make sense to write something custom for the
integration in question. This step is mandatory for all integrations.