From 11a7cbb7a9f0720213b0f4aea86a8d89de95aaa5 Mon Sep 17 00:00:00 2001
From: Niloth P <20315308+Niloth-p@users.noreply.github.com>
Date: Sun, 1 Jun 2025 13:35:28 +0530
Subject: [PATCH] integration-docs: Update the doc of the IRC bridge
integration.
---
zulip/integrations/bridge_with_irc/doc.md | 98 +++++++++++++----------
1 file changed, 55 insertions(+), 43 deletions(-)
diff --git a/zulip/integrations/bridge_with_irc/doc.md b/zulip/integrations/bridge_with_irc/doc.md
index e204754de..7f3d7971b 100644
--- a/zulip/integrations/bridge_with_irc/doc.md
+++ b/zulip/integrations/bridge_with_irc/doc.md
@@ -1,67 +1,79 @@
-Mirror an IRC channel in Zulip!
+# Zulip IRC Integration
-### Install the bridge software
+Mirror messages between an IRC channel and a Zulip channel in real-time!
-1. Clone the Zulip API repository, and install its dependencies.
+{start_tabs}
- ```
- git clone https://github.com/zulip/python-zulip-api.git
- cd python-zulip-api
- python3 ./tools/provision
- ```
+1. {!download-python-bindings.md!}
+
+1. {!install-requirements.md!}
+
+1. Register a nick that ends with the suffix `_zulip` on your IRC server.
- This will create a new Python virtualenv. You'll run the bridge service
- inside this virtualenv.
+1. {!create-a-generic-bot.md!}
-1. Activate the virtualenv by running the `source` command printed
- at the end of the output of the previous step.
+1. Download the `zuliprc` configuration file of your bot by clicking the
+ download () icon under the bot's name, and
+ save to `~/.zuliprc`.
-1. Go to the directory containing the bridge script if you haven't already done so
+1. [Subscribe the bot][subscribe-channels] to the Zulip channel where IRC
+ messages should be mirrored.
+
+1. Begin mirroring messages between the IRC channel and the Zulip channel
+ by running the `irc-mirror.py` script with the
+ [required command-line arguments](#required-arguments). Use the
+ [optional arguments](#optional-arguments) to configure the mirroring
+ behavior.
+
+ Here's an example command that mirrors messages between the
+ **#python-mypy** channel on the `irc.freenode.net` server and the "mypy"
+ topic on the **#irc-discussions** channel on Zulip:
```
- cd zulip/integrations/bridge_with_irc
+ python {{ integration_path }}/irc-mirror.py \
+ --irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \
+ --stream='irc-discussions' --topic='mypy'
```
-1. Install the bridge dependencies in your virtualenv, by running:
+1. Messages will be mirrored only when the terminal session with the bot
+ remains open. Consider using `screen` to run the bot in the background.
+ You can restart the integration at any time by re-running the
+ `irc-mirror.py` script.
+
+{end_tabs}
+
+You're done! Messages in your Zulip channel may look like:
- ```
- pip install -r requirements.txt
- ```
+
-### Configure the bridge
+Messages in your IRC channel may look like:
-1. {!create-a-generic-bot.md!}
- Download the bot's `zuliprc` configuration file to your computer.
+
-1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip
- stream that will contain the mirror.
+[subscribe-channels]: /help/manage-user-channel-subscriptions#subscribe-a-user-to-a-channel
-1. Inside the virtualenv you created above, run:
+### Configuration options
- ```
- python irc-mirror.py --irc-server=IRC_SERVER --channel= --nick-prefix= \
- --stream= [--topic=] \
- --site= --user= \
- --api-key=
- ```
+The integration script accepts the following command-line arguments:
- `--topic` is a Zulip topic, is optionally specified, defaults to "IRC".
+#### Required arguments
-Example command:
+- `--irc-server`: The IRC server to mirror.
-```
-./irc-mirror.py --irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \
---stream='test here' --topic='#mypy' \
---site="https://chat.zulip.org" --user=bot@email.com \
---api-key=DeaDbEEf
-```
+- `--nick-prefix`: Your registered IRC nick without the `_zulip` suffix.
-**Congratulations! You're done!**
+- `--channel`: The IRC channel to mirror.
-Your Zulip messages may look like:
+- `--stream`: The name of the Zulip channel you want to mirror. The default
+ channel name is **#general**.
-
+#### Optional arguments
-Your IRC messages may look like:
+- `--topic`: The name of the Zulip topic you want to receive and send
+ messages in. The default topic name is "IRC".
-
+- `--port`: The port to connect to the IRC server on. Defaults to 6667.
+
+- `--nickserv-pw`: Password corresponding to the IRC nick.
+
+- `--sasl-password`: Password for SASL authentication.