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.

api_docs/api-keys.md

@@ -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).
+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
 

api_docs/deploying-bots.md

@@ -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 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`;
 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,15 +233,14 @@ 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
+- 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
+- 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:
@@ -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)

api_docs/incoming-webhooks-overview.md

@@ -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)

api_docs/incoming-webhooks-walkthrough.md

@@ -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
+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)
   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
   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](
   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.
 
 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)

api_docs/installation-instructions.md

@@ -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)

api_docs/non-webhook-integrations.md

@@ -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)

api_docs/outgoing-webhooks.md

@@ -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

api_docs/running-bots.md

@@ -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
+{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
+
+1. Use the following command to start the bot process *(replacing
+   `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above)*:
 
-    * Run
-      ```
         zulip-run-bot <bot-name> --config-file ~/path/to/zuliprc
-      ```
 
-      (replacing `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above).
+1. Check the output of the command above to make sure your bot is running.
-
+   It should include the following line:
-    * Check the output of the command. It should include the following line:
 
         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
+environment where it'll stay up, by [deploying](/api/deploying-bots) it on a
-Zulip Botserver.
+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)

api_docs/writing-bots.md

@@ -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](
+{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:
+
+    ```
+    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.*
+    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)