Skip to content

Commit 42f10cc

Browse files
Niloth-pNiloth-p
committed
integration-docs: Migrate docs closer to their source code.
The integration docs of script integrations are moved from zulip/zulip to this repository to keep them closer to their integration scripts and READMEs.
1 parent 8c27331 commit 42f10cc

File tree

14 files changed

+807
-0
lines changed

14 files changed

+807
-0
lines changed

‎zulip/integrations/bridge_with_irc/doc.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Mirror an IRC channel in Zulip!
2+
3+
### Install the bridge software
4+
5+
1. Clone the Zulip API repository, and install its dependencies.
6+
7+
```
8+
git clone https://github.com/zulip/python-zulip-api.git
9+
cd python-zulip-api
10+
python3 ./tools/provision
11+
```
12+
13+
This will create a new Python virtualenv. You'll run the bridge service
14+
inside this virtualenv.
15+
16+
1. Activate the virtualenv by running the `source` command printed
17+
at the end of the output of the previous step.
18+
19+
1. Go to the directory containing the bridge script if you haven't already done so
20+
21+
```
22+
cd zulip/integrations/bridge_with_irc
23+
```
24+
25+
1. Install the bridge dependencies in your virtualenv, by running:
26+
27+
```
28+
pip install -r requirements.txt
29+
```
30+
31+
### Configure the bridge
32+
33+
1. {!create-a-generic-bot.md!}
34+
Download the bot's `zuliprc` configuration file to your computer.
35+
36+
1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip
37+
stream that will contain the mirror.
38+
39+
1. Inside the virtualenv you created above, run:
40+
41+
```
42+
python irc-mirror.py --irc-server=IRC_SERVER --channel=<CHANNEL> --nick-prefix=<NICK> \
43+
--stream=<STREAM> [--topic=<TOPIC>] \
44+
--site=<zulip.site> --user=<bot-email> \
45+
--api-key=<api-key>
46+
```
47+
48+
`--topic` is a Zulip topic, is optionally specified, defaults to "IRC".
49+
50+
Example command:
51+
52+
```
53+
./irc-mirror.py --irc-server=irc.freenode.net --channel='#python-mypy' --nick-prefix=irc_mirror \
54+
--stream='test here' --topic='#mypy' \
55+
--site="https://chat.zulip.org" --user=[email protected] \
56+
--api-key=DeaDbEEf
57+
```
58+
59+
**Congratulations! You're done!**
60+
61+
Your Zulip messages may look like:
62+
63+
![IRC message on Zulip](/static/images/integrations/irc/001.png)
64+
65+
Your IRC messages may look like:
66+
67+
![Zulip message on IRC](/static/images/integrations/irc/002.png)

‎zulip/integrations/bridge_with_matrix/doc.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Exchange messages between [matrix.org](https://matrix.org) and Zulip! If
2+
you're looking to mirror an IRC channel in particular, we recommend our
3+
[direct IRC integration](/integrations/doc/irc).
4+
5+
### Install the bridge software
6+
7+
1. Clone the Zulip API repository, and install its dependencies.
8+
9+
```
10+
git clone https://github.com/zulip/python-zulip-api.git
11+
cd python-zulip-api
12+
python3 ./tools/provision
13+
```
14+
15+
This will create a new Python virtualenv. You'll run the bridge service
16+
inside this virtualenv.
17+
18+
1. Activate the virtualenv by running the `source` command printed
19+
at the end of the output of the previous step.
20+
21+
1. Install the Matrix bridge software in your virtualenv, by running:
22+
23+
```
24+
pip install -r zulip/integrations/bridge_with_matrix/requirements.txt
25+
```
26+
27+
### Configure the bridge
28+
29+
1. {!create-a-generic-bot.md!}
30+
Download the bot's `zuliprc` configuration file to your computer.
31+
32+
1. [Subscribe the bot](/help/subscribe-users-to-a-channel) to the Zulip
33+
stream that will contain the mirror.
34+
35+
1. Inside the virtualenv you created above, run
36+
37+
```
38+
python zulip/integrations/bridge_with_matrix/matrix_bridge.py \
39+
--write-sample-config matrix_bridge.conf --from-zuliprc <path/to/zuliprc>
40+
```
41+
42+
where `<path/to/zuliprc>` is the path to the `zuliprc` file you downloaded.
43+
44+
1. Create a user on [matrix.org](https://matrix.org/) or another matrix
45+
server, preferably with a descriptive name like `zulip-bot`.
46+
47+
1. Edit `matrix_bridge.conf` to look like this:
48+
49+
```
50+
[zulip]
51+
email = [email protected]
52+
api_key = aPiKeY
53+
site = https://chat.zulip.org
54+
stream = "stream name"
55+
topic = "{{ integration_display_name }} mirror"
56+
[matrix]
57+
host = https://matrix.org
58+
username = <your matrix username>
59+
password = <your matrix password>
60+
room_id = #room:matrix.org
61+
```
62+
63+
The first three values should already be there; the rest you'll have to fill in.
64+
Make sure **stream** is set to the stream the bot is
65+
subscribed to.
66+
67+
{% if 'IRC' in integration_display_name %}
68+
69+
NOTE: For matrix.org, the `room_id` generally takes the form
70+
`#<irc_network>_#<channel>:matrix.org`. You can see the format for
71+
several popular IRC networks
72+
[here](https://github.com/matrix-org/matrix-appservice-irc/wiki/Bridged-IRC-networks), under
73+
the "Room alias format" column.
74+
75+
For example, the `room_id` for the `#zulip-test` channel on freenode is
76+
`#freenode_#zulip-test:matrix.org`.
77+
78+
{% endif %}
79+
80+
1. Run the following command to start the matrix bridge:
81+
82+
```
83+
python zulip/integrations/bridge_with_matrix/matrix_bridge.py -c matrix_bridge.conf
84+
```
85+
86+
!!! tip ""
87+
88+
You can customize the message formatting by
89+
editing the variables `MATRIX_MESSAGE_TEMPLATE` and `ZULIP_MESSAGE_TEMPLATE`
90+
in `zulip/integrations/bridge_with_matrix/matrix_bridge.py`.
91+
92+
**Note**: There are a handful of
93+
[IRC channels](https://github.com/matrix-org/matrix-appservice-irc/wiki/Channels-from-which-the-IRC-bridge-is-banned)
94+
that have temporarily banned the Matrix.org IRC bridge.
95+
You can't currently mirror those channels using this integration.

‎zulip/integrations/codebase/doc.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Zulip Codebase integration
2+
3+
Get Codebase notifications in Zulip!
4+
5+
{start_tabs}
6+
7+
1. [Create the channels](/help/create-a-channel) you’d like to use for
8+
Codebase notifications. There will be two types of notification
9+
messages: issue-related and commit-related.
10+
11+
1. {!create-an-incoming-webhook.md!}
12+
13+
1. {!download-python-bindings.md!}
14+
15+
1. Install the requirements for the integration script with:
16+
17+
`pip install /usr/local/share/zulip/integrations/codebase/requirements.txt`
18+
19+
1. {!change-zulip-config-file.md!}
20+
21+
Also add `ZULIP_TICKETS_STREAM_NAME` and `ZULIP_COMMITS_STREAM_NAME`
22+
with the names of the channels you created in step 1.
23+
24+
1. Go to your Codebase settings, and click on **My Profile**. Under
25+
**API Credentials**, you will find your API key and username.
26+
Edit the following lines in `zulip_codebase_config.py` to add your
27+
Codebase credentials:
28+
29+
```
30+
CODEBASE_API_USERNAME = "zulip-inc/user-name-123"
31+
CODEBASE_API_KEY = 0123456789abcdef0123456789abcdef
32+
```
33+
34+
!!! tip ""
35+
36+
Before your first run of the script, you may also want to configure
37+
the integration to mirror some number of hours of prior Codebase
38+
activity, e.g., `CODEBASE_INITIAL_HISTORY_HOURS = 10`.
39+
40+
1. Run the
41+
`/usr/local/share/zulip/integrations/codebase/zulip_codebase_mirror`
42+
script.
43+
44+
!!! tip ""
45+
46+
This script can be restarted, and it will resume from when it was
47+
last running.
48+
49+
{end_tabs}
50+
51+
{!congrats.md!}
52+
53+
![Codebase bot message](/static/images/integrations/codebase/001.png)

‎zulip/integrations/git/doc.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Get Zulip notifications for your Git repositories!
2+
3+
1. {!create-an-incoming-webhook.md!}
4+
5+
1. {!download-python-bindings.md!}
6+
7+
1. {!create-channel.md!}
8+
9+
1. {!change-zulip-config-file.md!}
10+
11+
You may also need to change the value of `STREAM_NAME`.
12+
13+
You can specify the branches that will be used for notifications by modifying
14+
the `commit_notice_destination` function. By default,
15+
pushes to the `main`, `master`, and `test-post-receive` branches will result in a
16+
notification.
17+
18+
1. Symlink `/usr/local/share/zulip/integrations/git/zulip_git_config.py`
19+
to the `.git/hooks` directory of your Git repository.
20+
21+
1. Symlink `/usr/local/share/zulip/integrations/git/post-receive`
22+
to the `.git/hooks` directory of your Git repository.
23+
24+
!!! tip ""
25+
26+
You can test the plugin without changing your `main` branch by
27+
pushing to the `test-post-receive` branch.
28+
29+
{!congrats.md!}
30+
31+
![Git bot message](/static/images/integrations/git/001.png)

‎zulip/integrations/google/doc.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
Get Google Calendar reminders in Zulip! This is a great way to see
2+
your reminders directly in your Zulip feed.
3+
4+
1. {!download-python-bindings.md!}
5+
6+
This bot should be set up on a trusted machine, because your API
7+
key is visible to local users through the command line or config
8+
file.
9+
10+
1. Next, follow the instructions for **Step 1** at
11+
[this link](https://developers.google.com/google-apps/calendar/quickstart/python)
12+
to get a `client_secret` file. Save this file as `client_secret.json`
13+
to your `~/` directory.
14+
15+
1. Next, install the latest Google API Client for Python by following the
16+
instructions on the
17+
[Google website](https://developers.google.com/api-client-library/python/start/installation).
18+
19+
1. In Zulip, go to your click on the cog in the top right corner, and
20+
then clicking on **Personal settings**.
21+
22+
1. Click on the tab that’s labeled **Account & privacy** and click on
23+
**Manage your API key**. Enter your password if prompted, and
24+
download the `zuliprc` file. Save this file as `.zuliprc` to your `~/`
25+
directory.
26+
27+
![Download zuliprc file](/static/images/integrations/google/calendar/001.png)
28+
29+
1. Run the `get-google-credentials` with this command:
30+
31+
python /usr/local/share/zulip/integrations/google/get-google-credentials
32+
33+
1. It should open up a browser and ask you for certain permissions. Give
34+
Zulip access, and move on to the next step. If it doesn’t open a
35+
browser, follow the instructions in the terminal window.
36+
37+
1. Now, all that’s left to do is to run the `gcal-bot` script, in the
38+
same directory as the `get-google-credentials` script, with the
39+
necessary parameters:
40+
41+
python /usr/local/share/zulip/integrations/google/gcal-bot --user [email protected]
42+
43+
The `--user` flag specifies the user to send the reminder to.
44+
45+
1. Don’t close the terminal window with the bot running (you can use
46+
`screen` if needed). You will only get reminders if the bot is still
47+
running.
48+
49+
{!congrats.md!}
50+
51+
![Calendar demo](/static/images/integrations/google/calendar/003.png)
52+
53+
## Supported parameters
54+
55+
There are two optional flags that you can specify when running this
56+
script:
57+
58+
* `--calendar`: This flag specifies the calendar to watch from the
59+
user’s Google account. By default, this flag is set to a user’s
60+
primary or default calendar. To specify a calendar, you need the
61+
calendar ID which can be obtained by going to Google Calendar and
62+
clicking on the wedge next to the calendar’s name. Click on settings
63+
in **Calendar settings** in the drop down, and look for the **Calendar
64+
Address** section. Copy the **Calendar ID** from the right side of the
65+
page and use that as the value for this flag.
66+
67+
![Specify a calendar](/static/images/integrations/google/calendar/002.png)
68+
69+
* `--interval`: This flag specifies the interval of time - in
70+
minutes - between receiving the reminder, and the actual event. For
71+
example, an interval of 30 minutes would mean that you would receive a
72+
reminder for an event 30 minutes before it is scheduled to occur.

0 commit comments

Comments
 (0)