Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

integrations-docs: Update Hello World for current macros and style. 

Updates the Hello World integration documentation and the section
of the related tutorial on documenting the example integration
for the currently used shared macro `create-bot-construct-url.md`.

Also, updates them to use the numbered style currently used in
the majority of the integrations documentation pages.
This commit is contained in:
Lauryn Menard 2022-11-28 16:03:59 +01:00 committed by Tim Abbott
parent 0375dbc5e9
commit c1d0ffe099
2 changed files with 29 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
templates/zerver/api/incoming-webhooks-walkthrough.md
View File

@ -420,27 +420,29 @@ Second, you need to write the actual documentation content in
```md ```md
Learn how Zulip integrations work with this simple Hello World example! Learn how Zulip integrations work with this simple Hello World example!
The Hello World webhook will use the `test` stream, which is 1. The Hello World webhook will use the `test` stream, which is created
created by default in the Zulip dev environment. If you are running by default in the Zulip development environment. If you are running
Zulip in production, you should make sure that this stream exists. Zulip in production, you should make sure that this stream exists.
Next, on your {{ settings_html|safe }}, create a Hello World bot. 1. {!create-bot-construct-url.md!}
Construct the URL for the Hello World bot using the API key and
stream name:
`{{ api_url }}/v1/external/helloworld?api_key=abcdefgh&stream=test`
To trigger a notification using this webhook, use 1. To trigger a notification using this example webhook, you can use
`send_webhook_fixture_message` from the Zulip command line: `send_webhook_fixture_message` from a [Zulip development
environment](https://zulip.readthedocs.io/en/latest/development/overview.html):
(zulip-py3-venv) vagrant@vagrant:/srv/zulip$ ```
./manage.py send_webhook_fixture_message \ (zulip-py3-venv) vagrant@vagrant:/srv/zulip$
--fixture=zerver/tests/fixtures/helloworld/hello.json \ ./manage.py send_webhook_fixture_message \
'--url=http://localhost:9991/api/v1/external/helloworld?api_key=<api_key>' > --fixture=zerver/tests/fixtures/helloworld/hello.json \
> '--url=http://localhost:9991/api/v1/external/helloworld?api_key=abcdefgh&stream=stream%20name;'
```
Or, use curl: Or, use curl:
curl -X POST -H "Content-Type: application/json" -d '{ "featured_title":"Marilyn Monroe", "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe" }' http://localhost:9991/api/v1/external/helloworld\?api_key\=<api_key> ```
curl -X POST -H "Content-Type: application/json" -d '{ "featured_title":"Marilyn Monroe", "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe" }' http://localhost:9991/api/v1/external/helloworld\?api_key=abcdefgh&stream=stream%20name;
```
{!congrats.md!} {!congrats.md!}
@ -448,9 +450,10 @@ Or, use curl:
``` ```
`{!congrats.md!}` is an example of a Markdown macro. Zulip has a macro-based `{!create-bot-construct-url.md!}` and `{!congrats.md!}` are examples of
Markdown/Jinja2 framework that includes macros for common instructions in a Markdown macro. Zulip has a macro-based Markdown/Jinja2 framework that
Zulip's webhooks/integrations documentation. includes macros for common instructions in Zulip's webhooks/integrations
documentation.
See See
[our guide on documenting an integration][integration-docs-guide] [our guide on documenting an integration][integration-docs-guide]

18
zerver/webhooks/helloworld/doc.md
View File

@ -3,29 +3,27 @@ Learn how Zulip integrations work with this simple Hello World example!
This webhook is Zulip's official [example This webhook is Zulip's official [example
integration](/api/incoming-webhooks-walkthrough). integration](/api/incoming-webhooks-walkthrough).
1. The Hello World webhook will use the `test` stream, which is 1. The Hello World webhook will use the `test` stream, which is created
by default in the Zulip dev environment. If you are running by default in the Zulip development environment. If you are running
Zulip in production, you should make sure that this stream exists. Zulip in production, you should make sure that this stream exists.
1. Next, on your {{ settings_html|safe }}, create a Hello World bot. 1. {!create-bot-construct-url.md!}
the URL for the Hello World bot using the API key and
stream name:
`{{ api_url }}/v1/external/helloworld?api_key=abcdefgh&stream=test` 1. To trigger a notification using this example webhook, you can use
1. To trigger a notification using this webhook, you can use
`send_webhook_fixture_message` from a [Zulip development `send_webhook_fixture_message` from a [Zulip development
environment](https://zulip.readthedocs.io/en/latest/development/overview.html): environment](https://zulip.readthedocs.io/en/latest/development/overview.html):
```
(zulip-py3-venv) vagrant@vagrant:/srv/zulip$ (zulip-py3-venv) vagrant@vagrant:/srv/zulip$
./manage.py send_webhook_fixture_message \ ./manage.py send_webhook_fixture_message \
> --fixture=zerver/tests/fixtures/helloworld/hello.json \ > --fixture=zerver/tests/fixtures/helloworld/hello.json \
> '--url=http://localhost:9991/api/v1/external/helloworld?api_key=<api_key>' > '--url=http://localhost:9991/api/v1/external/helloworld?api_key=abcdefgh&stream=stream%20name;'
```
Or, use curl: Or, use curl:
``` ```
curl -X POST -H "Content-Type: application/json" -d '{ "featured_title":"Marilyn Monroe", "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe" }' http://localhost:9991/api/v1/external/helloworld\?api_key\=<api_key> curl -X POST -H "Content-Type: application/json" -d '{ "featured_title":"Marilyn Monroe", "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe" }' http://localhost:9991/api/v1/external/helloworld\?api_key=abcdefgh&stream=stream%20name;
``` ```
{!congrats.md!} {!congrats.md!}