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
clients, such as the Python bindings, we recommend [downloading a `zuliprc`
file](/api/configuring-python-bindings#download-a-zuliprc-file).
This file contains an API key along with other necessary configuration values
for using the Zulip API with a specific account on a Zulip server.
file](/api/configuring-python-bindings#download-a-zuliprc-file). This file
contains an API key and other necessary configuration values for using the
Zulip API with a specific account on a Zulip server.
## 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/`:
```json
```
{
"message":{
"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.
1. The Botserver searches for a bot to handle the message.
1. The Botserver executes your bot's `handle_message` code.
1. The Botserver searches for a bot to handle the message, and executes your
bot's `handle_message` code.
Your bot's code should work just like it does with `zulip-run-bot`;
for example, you reply using
@ -75,6 +74,7 @@ pip3 install zulip_botserver
### Running a bot using the Zulip Botserver
{start_tabs}
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
test a normal bot.
{end_tabs}
### Running multiple bots using the Zulip Botserver
The Zulip Botserver also supports running multiple bots from a single
Botserver process. You can do this with the following procedure.
{start_tabs}
1. Download the `botserverrc` from the `your-bots` settings page, using
the "Download config of all active outgoing webhook bots in Zulip
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`.
{end_tabs}
### Running Zulip Botserver with supervisord
[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 it manually.
{start_tabs}
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
your *supervisord* configuration.
{end_tabs}
If you are hosting the Botserver yourself (as opposed to using a
hosting service that provides SSL), we recommend securing your
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
1. Make sure the API key you're using is for an [outgoing webhook
bot](/api/outgoing-webhooks) and you've
correctly configured the URL for your Botserver.
- Make sure the API key you're using is for an [outgoing webhook
bot](/api/outgoing-webhooks) and you've
correctly configured the URL for your Botserver.
1. Your Botserver needs to be accessible from your Zulip server over
HTTP(S). Make sure any firewall allows the connection. We
recommend using [zulip-run-bot](running-bots) instead for
development/testing on a laptop or other non-server system.
If your Zulip server is self-hosted, you can test by running `curl
http://zulipbotserver.example.com:5002` from your Zulip server;
the output should be:
- Your Botserver needs to be accessible from your Zulip server over
HTTP(S). Make sure any firewall allows the connection. We
recommend using [zulip-run-bot](running-bots) instead for
development/testing on a laptop or other non-server system.
If your Zulip server is self-hosted, you can test by running `curl
http://zulipbotserver.example.com:5002` from your Zulip server;
the output should be:
```
$ 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>
<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
[add-bot]: /help/add-a-bot-or-integration
[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
This is the GUI tool.
{start_tabs}
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.
**Integration** - One of the integrations.
**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.
3. Click **Send**!
1. Click **Send**!
{end_tabs}
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.
@ -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
When you have finished your webhook integration and are ready for it to be
available in the Zulip product, follow these steps to prepare your pull
request:
When you have finished your webhook integration, follow these guidelines before
pushing the code to your fork and submitting a pull request to zulip/zulip:
1. Run tests including linters and ensure you have addressed any issues they
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.
2. Read through [Code styles and conventions](
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.
3. Take a look at your Git history to ensure your commits have been clear and
logical (see [Commit discipline](
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,
you'll want to squash your changes into a single commit and include a good,
clear commit message.
4. Push code to your fork.
5. Submit a pull request to zulip/zulip.
- Run tests including linters and ensure you have addressed any issues they
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.
- Read through [Code styles and conventions](
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.
- Take a look at your Git history to ensure your commits have been clear and
logical (see [Commit discipline](
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,
you'll want to squash your changes into a single commit and include a good,
clear commit message.
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).
@ -652,3 +653,8 @@ with a string describing the unsupported event type, like so:
```
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)
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
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
(by shelling out or otherwise), passing in the required data. Our preferred
model for these is to ship these integrations in the
[Zulip Python API distribution](https://github.com/zulip/python-zulip-api/tree/main/zulip),
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
existing software. These are often more work, but for some products are the
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
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:
@ -51,3 +51,9 @@ examples of ideal UAs are:
* The [general advice](/api/incoming-webhooks-overview#general-advice) for
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:
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.
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.
## 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.**
1. Go to your Zulip account and
[add a bot](/help/add-a-bot-or-integration). Use **Generic bot** as the bot type.
{start_tabs}
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
[here](
writing-bots#installing-a-development-version-of-the-zulip-bots-package)
to install the latest development version of the package.*
1. Use the following command to install the
[`zulip_bots` Python package](https://pypi.org/project/zulip-bots/):
1. Start the bot process on your computer.
pip3 install zulip_bots
* Run
```
zulip-run-bot <bot-name> --config-file ~/path/to/zuliprc
```
1. Use the following command to start the bot process *(replacing
`~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above)*:
(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
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
Zulip Botserver.
environment where it'll stay up, by [deploying](/api/deploying-bots) it on a
server using the Zulip Botserver.
## Common problems
@ -63,3 +66,9 @@ Zulip Botserver.
the Vagrant environment.
* Some bots require Python 3. Try switching to a Python 3 environment before running
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
1. `git clone https://github.com/zulip/python-zulip-api.git` - clone the [python-zulip-api](
https://github.com/zulip/python-zulip-api) repository.
{start_tabs}
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`;
run that command to enter the new virtualenv.
1. Navigate into your cloned repository:
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
`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.*
1. Install all requirements in a Python virtualenv:
```
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
@ -512,3 +530,10 @@ The long-term plan for this bot system is to allow the same
received from Zulip's outgoing webhooks integration.
* For bots merged into the mainline Zulip codebase, enabled via a
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)