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

View File

@ -420,27 +420,29 @@ Second, you need to write the actual documentation content in
```md
Learn how Zulip integrations work with this simple Hello World example!
The Hello World webhook will use the `test` stream, which is
created by default in the Zulip dev environment. If you are running
1. The Hello World webhook will use the `test` stream, which is created
by default in the Zulip development environment. If you are running
Zulip in production, you should make sure that this stream exists.
Next, on your {{ settings_html|safe }}, create a Hello World bot.
Construct the URL for the Hello World bot using the API key and
stream name:
1. {!create-bot-construct-url.md!}
`{{ api_url }}/v1/external/helloworld?api_key=abcdefgh&stream=test`
To trigger a notification using this webhook, use
`send_webhook_fixture_message` from the Zulip command line:
1. To trigger a notification using this example webhook, you can use
`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 \
--fixture=zerver/tests/fixtures/helloworld/hello.json \
'--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:
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!}
@ -448,9 +450,10 @@ Or, use curl:
```
`{!congrats.md!}` is an example of a Markdown macro. Zulip has a macro-based
Markdown/Jinja2 framework that includes macros for common instructions in
Zulip's webhooks/integrations documentation.
`{!create-bot-construct-url.md!}` and `{!congrats.md!}` are examples of
a Markdown macro. Zulip has a macro-based Markdown/Jinja2 framework that
includes macros for common instructions in Zulip's webhooks/integrations
documentation.
See
[our guide on documenting an integration][integration-docs-guide]

View File

@ -3,29 +3,27 @@ Learn how Zulip integrations work with this simple Hello World example!
This webhook is Zulip's official [example
integration](/api/incoming-webhooks-walkthrough).
1. The Hello World webhook will use the `test` stream, which is
by default in the Zulip dev environment. If you are running
1. The Hello World webhook will use the `test` stream, which is created
by default in the Zulip development environment. If you are running
Zulip in production, you should make sure that this stream exists.
1. Next, on your {{ settings_html|safe }}, create a Hello World bot.
the URL for the Hello World bot using the API key and
stream name:
1. {!create-bot-construct-url.md!}
`{{ api_url }}/v1/external/helloworld?api_key=abcdefgh&stream=test`
1. To trigger a notification using this webhook, you can use
1. To trigger a notification using this example webhook, you can use
`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 \
> --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:
```
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!}