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

api-docs: Use `start_tabs` formatting and add "Related articles". 

- Updates API docs that have numbered instructions to use the
  `{start_tabs}` formatting we use in the help center.
- Cleans up formatting and revises documentation that shouldn't
  be formatted as a numbered instructions block.
- Cross-links related articles.

Fixes #28876.
This commit is contained in:
David Rosa 2024-02-09 16:10:17 -07:00 committed by Tim Abbott
parent 96daef400e
commit 3c0cb4c6a2
9 changed files with 145 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
api_docs/api-keys.md
View File

@ -2,9 +2,9 @@
An **API key** is how a bot identifies itself to Zulip. For the official An **API key** is how a bot identifies itself to Zulip. For the official
clients, such as the Python bindings, we recommend [downloading a `zuliprc` clients, such as the Python bindings, we recommend [downloading a `zuliprc`
file](/api/configuring-python-bindings#download-a-zuliprc-file). file](/api/configuring-python-bindings#download-a-zuliprc-file). This file
This file contains an API key along with other necessary configuration values contains an API key and other necessary configuration values for using the
for using the Zulip API with a specific account on a Zulip server. Zulip API with a specific account on a Zulip server.
## Get a bot's API key ## Get a bot's API key

45
api_docs/deploying-bots.md
View File

@ -44,7 +44,7 @@ Botserver interaction are:
1. The Zulip server sends a POST request to the Botserver on `https://bot-server.example.com/`: 1. The Zulip server sends a POST request to the Botserver on `https://bot-server.example.com/`:
```json ```
{ {
"message":{ "message":{
"content":"@**My Bot User** hello world", "content":"@**My Bot User** hello world",
@ -57,9 +57,8 @@ Botserver interaction are:
This URL is configured in the Zulip web-app in your Bot User's settings. This URL is configured in the Zulip web-app in your Bot User's settings.
1. The Botserver searches for a bot to handle the message. 1. The Botserver searches for a bot to handle the message, and executes your
bot's `handle_message` code.
1. The Botserver executes your bot's `handle_message` code.
Your bot's code should work just like it does with `zulip-run-bot`; Your bot's code should work just like it does with `zulip-run-bot`;
for example, you reply using for example, you reply using
@ -75,6 +74,7 @@ pip3 install zulip_botserver
### Running a bot using the Zulip Botserver ### Running a bot using the Zulip Botserver
{start_tabs}
1. Construct the URL for your bot, which will be of the form: 1. Construct the URL for your bot, which will be of the form:
@ -108,11 +108,15 @@ pip3 install zulip_botserver
1. Congrats, everything is set up! Test your Botserver like you would 1. Congrats, everything is set up! Test your Botserver like you would
test a normal bot. test a normal bot.
{end_tabs}
### Running multiple bots using the Zulip Botserver ### Running multiple bots using the Zulip Botserver
The Zulip Botserver also supports running multiple bots from a single The Zulip Botserver also supports running multiple bots from a single
Botserver process. You can do this with the following procedure. Botserver process. You can do this with the following procedure.
{start_tabs}
1. Download the `botserverrc` from the `your-bots` settings page, using 1. Download the `botserverrc` from the `your-bots` settings page, using
the "Download config of all active outgoing webhook bots in Zulip the "Download config of all active outgoing webhook bots in Zulip
Botserver format." option at the top. Botserver format." option at the top.
@ -160,6 +164,8 @@ Botserver process. You can do this with the following procedure.
If omitted, `hostname` defaults to `127.0.0.1` and `port` to `5002`. If omitted, `hostname` defaults to `127.0.0.1` and `port` to `5002`.
{end_tabs}
### Running Zulip Botserver with supervisord ### Running Zulip Botserver with supervisord
[supervisord](http://supervisord.org/) is a popular tool for running [supervisord](http://supervisord.org/) is a popular tool for running
@ -170,6 +176,8 @@ section documents how to run the Zulip Botserver using *supervisord*.
Running the Zulip Botserver with *supervisord* works almost like Running the Zulip Botserver with *supervisord* works almost like
running it manually. running it manually.
{start_tabs}
1. Install *supervisord* via your package manager; e.g. on Debian/Ubuntu: 1. Install *supervisord* via your package manager; e.g. on Debian/Ubuntu:
``` ```
@ -216,6 +224,8 @@ running it manually.
The standard output of the Botserver will be logged to the path in The standard output of the Botserver will be logged to the path in
your *supervisord* configuration. your *supervisord* configuration.
{end_tabs}
If you are hosting the Botserver yourself (as opposed to using a If you are hosting the Botserver yourself (as opposed to using a
hosting service that provides SSL), we recommend securing your hosting service that provides SSL), we recommend securing your
Botserver with SSL using an `nginx` or `Apache` reverse proxy and Botserver with SSL using an `nginx` or `Apache` reverse proxy and
@ -223,18 +233,17 @@ Botserver with SSL using an `nginx` or `Apache` reverse proxy and
### Troubleshooting ### Troubleshooting
1. Make sure the API key you're using is for an [outgoing webhook - Make sure the API key you're using is for an [outgoing webhook
bot](/api/outgoing-webhooks) and you've bot](/api/outgoing-webhooks) and you've
correctly configured the URL for your Botserver. correctly configured the URL for your Botserver.
1. Your Botserver needs to be accessible from your Zulip server over - Your Botserver needs to be accessible from your Zulip server over
HTTP(S). Make sure any firewall allows the connection. We HTTP(S). Make sure any firewall allows the connection. We
recommend using [zulip-run-bot](running-bots) instead for recommend using [zulip-run-bot](running-bots) instead for
development/testing on a laptop or other non-server system. development/testing on a laptop or other non-server system.
If your Zulip server is self-hosted, you can test by running `curl
If your Zulip server is self-hosted, you can test by running `curl http://zulipbotserver.example.com:5002` from your Zulip server;
http://zulipbotserver.example.com:5002` from your Zulip server; the output should be:
the output should be:
``` ```
$ curl http://zulipbotserver.example.com:5002/ $ curl http://zulipbotserver.example.com:5002/
@ -243,3 +252,9 @@ Botserver with SSL using an `nginx` or `Apache` reverse proxy and
<h1>Method Not Allowed</h1> <h1>Method Not Allowed</h1>
<p>The method is not allowed for the requested URL.</p> <p>The method is not allowed for the requested URL.</p>
``` ```
## Related articles
* [Non-webhook integrations](/api/non-webhook-integrations)
* [Running bots](/api/running-bots)
* [Writing bots](/api/writing-bots)

6
api_docs/incoming-webhooks-overview.md
View File

@ -197,3 +197,9 @@ Parameters accepted in the URL include:
[browse-streams]: /help/browse-and-subscribe-to-streams [browse-streams]: /help/browse-and-subscribe-to-streams
[add-bot]: /help/add-a-bot-or-integration [add-bot]: /help/add-a-bot-or-integration
[url-encoder]: https://www.urlencoder.org/ [url-encoder]: https://www.urlencoder.org/
## Related articles
* [Integrations overview](/api/integrations-overview)
* [Incoming webhook walkthrough](/api/incoming-webhooks-walkthrough)
* [Non-webhook integrations](/api/non-webhook-integrations)

44
api_docs/incoming-webhooks-walkthrough.md
View File

@ -289,15 +289,19 @@ the [management commands][management-commands] documentation.
### Integrations Dev Panel ### Integrations Dev Panel
This is the GUI tool. This is the GUI tool.
{start_tabs}
1. Run `./tools/run-dev` then go to http://localhost:9991/devtools/integrations/. 1. Run `./tools/run-dev` then go to http://localhost:9991/devtools/integrations/.
2. Set the following mandatory fields: 1. Set the following mandatory fields:
**Bot** - Any incoming webhook bot. **Bot** - Any incoming webhook bot.
**Integration** - One of the integrations. **Integration** - One of the integrations.
**Fixture** - Though not mandatory, it's recommended that you select one and then tweak it if necessary. **Fixture** - Though not mandatory, it's recommended that you select one and then tweak it if necessary.
The remaining fields are optional, and the URL will automatically be generated. The remaining fields are optional, and the URL will automatically be generated.
3. Click **Send**! 1. Click **Send**!
{end_tabs}
By opening Zulip in one tab and then this tool in another, you can quickly tweak By opening Zulip in one tab and then this tool in another, you can quickly tweak
your code and send sample messages for many different test fixtures. your code and send sample messages for many different test fixtures.
@ -480,24 +484,21 @@ screenshot. Mostly you should plan on templating off an existing guide, like
## Step 7: Preparing a pull request to zulip/zulip ## Step 7: Preparing a pull request to zulip/zulip
When you have finished your webhook integration and are ready for it to be When you have finished your webhook integration, follow these guidelines before
available in the Zulip product, follow these steps to prepare your pull pushing the code to your fork and submitting a pull request to zulip/zulip:
request:
1. Run tests including linters and ensure you have addressed any issues they - Run tests including linters and ensure you have addressed any issues they
report. See [Testing](https://zulip.readthedocs.io/en/latest/testing/testing.html) report. See [Testing](https://zulip.readthedocs.io/en/latest/testing/testing.html)
and [Linters](https://zulip.readthedocs.io/en/latest/testing/linters.html) for details. and [Linters](https://zulip.readthedocs.io/en/latest/testing/linters.html) for details.
2. Read through [Code styles and conventions]( - Read through [Code styles and conventions](
https://zulip.readthedocs.io/en/latest/contributing/code-style.html) and take a look https://zulip.readthedocs.io/en/latest/contributing/code-style.html) and take a look
through your code to double-check that you've followed Zulip's guidelines. through your code to double-check that you've followed Zulip's guidelines.
3. Take a look at your Git history to ensure your commits have been clear and - Take a look at your Git history to ensure your commits have been clear and
logical (see [Commit discipline]( logical (see [Commit discipline](
https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html) for tips). If not, https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html) for tips). If not,
consider revising them with `git rebase --interactive`. For most incoming webhooks, consider revising them with `git rebase --interactive`. For most incoming webhooks,
you'll want to squash your changes into a single commit and include a good, you'll want to squash your changes into a single commit and include a good,
clear commit message. clear commit message.
4. Push code to your fork.
5. Submit a pull request to zulip/zulip.
If you would like feedback on your integration as you go, feel free to post a If you would like feedback on your integration as you go, feel free to post a
message on the [public Zulip instance](https://chat.zulip.org/#narrow/stream/integrations). message on the [public Zulip instance](https://chat.zulip.org/#narrow/stream/integrations).
@ -652,3 +653,8 @@ with a string describing the unsupported event type, like so:
``` ```
raise UnsupportedWebhookEventTypeError(event_type) raise UnsupportedWebhookEventTypeError(event_type)
``` ```
## Related articles
* [Integrations overview](/api/integrations-overview)
* [Incoming webhook integrations](/api/incoming-webhooks-overview)

4
api_docs/installation-instructions.md
View File

@ -40,3 +40,7 @@ No download required!
See also [user-contributed client libraries](/api/client-libraries) See also [user-contributed client libraries](/api/client-libraries)
for many other languages. for many other languages.
## Related articles
* [Configuring the Python bindings](/api/configuring-python-bindings)

12
api_docs/non-webhook-integrations.md
View File

@ -4,14 +4,14 @@
fastest to write, but sometimes a third-party product just doesn't support fastest to write, but sometimes a third-party product just doesn't support
them. Zulip supports several other types of integrations. them. Zulip supports several other types of integrations.
1. **Python script integrations** * **Python script integrations**
(examples: SVN, Git), where we can get the service to call our integration (examples: SVN, Git), where we can get the service to call our integration
(by shelling out or otherwise), passing in the required data. Our preferred (by shelling out or otherwise), passing in the required data. Our preferred
model for these is to ship these integrations in the model for these is to ship these integrations in the
[Zulip Python API distribution](https://github.com/zulip/python-zulip-api/tree/main/zulip), [Zulip Python API distribution](https://github.com/zulip/python-zulip-api/tree/main/zulip),
within the `integrations` directory there. within the `integrations` directory there.
1. **Plugin integrations** (examples: * **Plugin integrations** (examples:
Jenkins, Hubot, Trac) where the user needs to install a plugin into their Jenkins, Hubot, Trac) where the user needs to install a plugin into their
existing software. These are often more work, but for some products are the existing software. These are often more work, but for some products are the
only way to integrate with the product at all. only way to integrate with the product at all.
@ -20,7 +20,7 @@ them. Zulip supports several other types of integrations.
documentation for the third party software in order to learn how to documentation for the third party software in order to learn how to
write the integration. write the integration.
1. **Interactive bots**. See [Writing bots](/api/writing-bots). * **Interactive bots**. See [Writing bots](/api/writing-bots).
A few notes on how to do these: A few notes on how to do these:
@ -51,3 +51,9 @@ examples of ideal UAs are:
* The [general advice](/api/incoming-webhooks-overview#general-advice) for * The [general advice](/api/incoming-webhooks-overview#general-advice) for
webhook integrations applies here as well. webhook integrations applies here as well.
## Related articles
* [Running bots](/api/running-bots)
* [Deploying bots](/api/deploying-bots)
* [Writing bots](/api/writing-bots)

4
api_docs/outgoing-webhooks.md
View File

@ -29,9 +29,9 @@ To register an outgoing webhook:
There are currently two ways to trigger an outgoing webhook: There are currently two ways to trigger an outgoing webhook:
1. **@-mention** the bot user in a stream. If the bot replies, its * **@-mention** the bot user in a stream. If the bot replies, its
reply will be sent to that stream and topic. reply will be sent to that stream and topic.
2. **Send a direct message** with the bot as one of the recipients. * **Send a direct message** with the bot as one of the recipients.
If the bot replies, its reply will be sent to that thread. If the bot replies, its reply will be sent to that thread.
## Timeouts ## Timeouts

49
api_docs/running-bots.md
View File

@ -20,39 +20,42 @@ You'll need:
**Note: Please be considerate when testing experimental bots on public servers such as chat.zulip.org.** **Note: Please be considerate when testing experimental bots on public servers such as chat.zulip.org.**
1. Go to your Zulip account and {start_tabs}
[add a bot](/help/add-a-bot-or-integration). Use **Generic bot** as the bot type.
1. Download the bot's `zuliprc` configuration file to your computer. 1. [Create a bot](/help/add-a-bot-or-integration), making sure to select
**Generic bot** as the **Bot type**.
1. Download the `zulip_bots` Python package to your computer using `pip3 install zulip_bots`. 1. [Download the bot's `zuliprc` file](/api/configuring-python-bindings#download-a-zuliprc-file).
*Note: Click 1. Use the following command to install the
[here]( [`zulip_bots` Python package](https://pypi.org/project/zulip-bots/):
writing-bots#installing-a-development-version-of-the-zulip-bots-package)
to install the latest development version of the package.*
1. Start the bot process on your computer. pip3 install zulip_bots
* Run 1. Use the following command to start the bot process *(replacing
``` `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above)*:
zulip-run-bot <bot-name> --config-file ~/path/to/zuliprc
```
(replacing `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above). zulip-run-bot <bot-name> --config-file ~/path/to/zuliprc
* Check the output of the command. It should include the following line: 1. Check the output of the command above to make sure your bot is running.
It should include the following line:
INFO:root:starting message handling... INFO:root:starting message handling...
Congrats! Your bot is running. 1. Test your setup by [starting a new direct message](/help/starting-a-new-direct-message)
with the bot or [mentioning](/help/mention-a-user-or-group) the bot on a stream.
1. To talk with the bot, at-mention its name, like `@**bot-name**`. !!! tip ""
To use the latest development version of the `zulip_bots` package, follow
[these steps](writing-bots#installing-a-development-version-of-the-zulip-bots-package).
{end_tabs}
You can now play around with the bot and get it configured the way you You can now play around with the bot and get it configured the way you
like. Eventually, you'll probably want to run it in a production like. Eventually, you'll probably want to run it in a production
environment where it'll stay up, by [deploying](/api/deploying-bots) it on a server using the environment where it'll stay up, by [deploying](/api/deploying-bots) it on a
Zulip Botserver. server using the Zulip Botserver.
## Common problems ## Common problems
@ -63,3 +66,9 @@ Zulip Botserver.
the Vagrant environment. the Vagrant environment.
* Some bots require Python 3. Try switching to a Python 3 environment before running * Some bots require Python 3. Try switching to a Python 3 environment before running
your bot. your bot.
## Related articles
* [Non-webhook integrations](/api/non-webhook-integrations)
* [Deploying bots](/api/deploying-bots)
* [Writing bots](/api/writing-bots)

49
api_docs/writing-bots.md
View File

@ -17,23 +17,41 @@ On this page you'll find:
## Installing a development version of the Zulip bots package ## Installing a development version of the Zulip bots package
1. `git clone https://github.com/zulip/python-zulip-api.git` - clone the [python-zulip-api]( {start_tabs}
https://github.com/zulip/python-zulip-api) repository.
2. `cd python-zulip-api` - navigate into your cloned repository. 1. Clone the [python-zulip-api](https://github.com/zulip/python-zulip-api)
repository:
3. `python3 ./tools/provision` - install all requirements in a Python virtualenv. ```
git clone https://github.com/zulip/python-zulip-api.git
```
4. The output of `provision` will end with a command of the form `source .../activate`; 1. Navigate into your cloned repository:
run that command to enter the new virtualenv.
5. *Finished*. You should now see the name of your venv preceding your prompt, ```
e.g. `(zulip-api-py3-venv)`. cd python-zulip-api
```
*Hint: `provision` installs the `zulip`, `zulip_bots`, and 1. Install all requirements in a Python virtualenv:
`zulip_botserver` packages in developer mode. This enables you to
modify these packages and then run your modified code without ```
having to first re-install the packages or re-provision.* python3 ./tools/provision
```
1. Run the command provided in the final output of the `provision` process to
enter the new virtualenv. The command will be of the form `source .../activate`.
1. You should now see the name of your virtualenv preceding your prompt e.g.,
`(zulip-api-py3-venv)`.
!!! tip ""
`provision` installs the `zulip`, `zulip_bots`, and
`zulip_botserver` packages in developer mode. This enables you to
modify these packages and then run your modified code without
having to first re-install the packages or re-provision.
{end_tabs}
## Writing a bot ## Writing a bot
@ -512,3 +530,10 @@ The long-term plan for this bot system is to allow the same
received from Zulip's outgoing webhooks integration. received from Zulip's outgoing webhooks integration.
* For bots merged into the mainline Zulip codebase, enabled via a * For bots merged into the mainline Zulip codebase, enabled via a
button in the Zulip web UI, with no code deployment effort required. button in the Zulip web UI, with no code deployment effort required.
## Related articles
* [Non-webhook integrations](/api/non-webhook-integrations)
* [Running bots](/api/running-bots)
* [Deploying bots](/api/deploying-bots)
* [Configuring the Python bindings](/api/configuring-python-bindings)