paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

integration-docs: Migrate PythonAPIIntegration docs.

Browse Source 
To zulip/python-zulip-api, to keep them closer to their source code.

- Renamed the generate_zulip_bots_static_files to
generate_bots_integrations_static_files to accomodate the new function.
- Added a new function to
tools/setup/generate_bots_integrations_static_files to copy the
integration docs into static/generated/integrations.
- Updated integrations.py and computed_settings.py to use the new doc
paths.
- Deleted the affected integration docs.
- Updated the dependency URL.
This commit is contained in:
Niloth P
2025-03-12 12:04:27 +05:30
committed by Tim Abbott
parent e76ace28d2
commit b2910aa05c
22 changed files with 57 additions and 739 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
pyproject.toml
View File

@@ -315,7 +315,7 @@ talon-core = { url = "https://github.com/zulip/talon/archive/e87a64dccc3c5ee1b8e
# version from Git rather than a PyPI release. Keeping everything in one
# repository simplifies the process of implementing and documenting new bots for
# new contributors.
zulip = { url = "https://github.com/zulip/python-zulip-api/archive/0.9.0.zip", subdirectory = "zulip" }
zulip = { url = "https://github.com/zulip/python-zulip-api/archive/9e131ac626976b9c3da6c11b6365b4939656f7c3.zip", subdirectory = "zulip" }
zulip-bots = { url = "https://github.com/zulip/python-zulip-api/archive/0.9.0.zip", subdirectory = "zulip_bots" }
# zulip's linting framework - zulint
@@ -388,6 +388,7 @@ module = [
"fakeldap.*",
"firebase_admin.*",
"gitlint.*",
"integrations.*",
"jsonref.*",
"ldap.*", # https://github.com/python-ldap/python-ldap/issues/368
"onelogin.*",

2
static/.gitignore vendored
View File

@@ -5,5 +5,7 @@
# Copied zulip_bots package
/generated/bots/
# Copied integrations package
/generated/integrations/
# From emoji
/generated/emoji

53
templates/zerver/integrations/codebase.md
View File

@@ -1,53 +0,0 @@
# Zulip Codebase integration
Get Codebase notifications in Zulip!
{start_tabs}
1. [Create the channels](/help/create-a-channel) you’d like to use for
Codebase notifications. There will be two types of notification
messages: issue-related and commit-related.
1. {!create-an-incoming-webhook.md!}
1. {!download-python-bindings.md!}
1. Install the requirements for the integration script with:
`pip install /usr/local/share/zulip/integrations/codebase/requirements.txt`
1. {!change-zulip-config-file.md!}
Also add `ZULIP_TICKETS_STREAM_NAME` and `ZULIP_COMMITS_STREAM_NAME`
with the names of the channels you created in step 1.
1. Go to your Codebase settings, and click on **My Profile**. Under
**API Credentials**, you will find your API key and username.
Edit the following lines in `zulip_codebase_config.py` to add your
Codebase credentials:
```
CODEBASE_API_USERNAME = "zulip-inc/user-name-123"
CODEBASE_API_KEY = 0123456789abcdef0123456789abcdef
```
!!! tip ""
Before your first run of the script, you may also want to configure
the integration to mirror some number of hours of prior Codebase
activity, e.g., `CODEBASE_INITIAL_HISTORY_HOURS = 10`.
1. Run the
`/usr/local/share/zulip/integrations/codebase/zulip_codebase_mirror`
script.
!!! tip ""
This script can be restarted, and it will resume from when it was
last running.
{end_tabs}
{!congrats.md!}
![Codebase bot message](/static/images/integrations/codebase/001.png)

31
templates/zerver/integrations/git.md
View File

@@ -1,31 +0,0 @@
Get Zulip notifications for your Git repositories!
1. {!create-an-incoming-webhook.md!}
1. {!download-python-bindings.md!}
1. {!create-channel.md!}
1. {!change-zulip-config-file.md!}
You may also need to change the value of `STREAM_NAME`.
You can specify the branches that will be used for notifications by modifying
the `commit_notice_destination` function. By default,
pushes to the `main`, `master`, and `test-post-receive` branches will result in a
notification.
1. Symlink `/usr/local/share/zulip/integrations/git/zulip_git_config.py`
to the `.git/hooks` directory of your Git repository.
1. Symlink `/usr/local/share/zulip/integrations/git/post-receive`
to the `.git/hooks` directory of your Git repository.
!!! tip ""
You can test the plugin without changing your `main` branch by
pushing to the `test-post-receive` branch.
{!congrats.md!}
![Git bot message](/static/images/integrations/git/001.png)

72
templates/zerver/integrations/google-calendar.md
View File

@@ -1,72 +0,0 @@
Get Google Calendar reminders in Zulip! This is a great way to see
your reminders directly in your Zulip feed.
1. {!download-python-bindings.md!}
This bot should be set up on a trusted machine, because your API
key is visible to local users through the command line or config
file.
1. Next, follow the instructions for **Step 1** at
[this link](https://developers.google.com/google-apps/calendar/quickstart/python)
to get a `client_secret` file. Save this file as `client_secret.json`
to your `~/` directory.
1. Next, install the latest Google API Client for Python by following the
instructions on the
[Google website](https://developers.google.com/api-client-library/python/start/installation).
1. In Zulip, go to your click on the cog in the top right corner, and
then clicking on **Personal settings**.
1. Click on the tab that’s labeled **Account & privacy** and click on
**Manage your API key**. Enter your password if prompted, and
download the `zuliprc` file. Save this file as `.zuliprc` to your `~/`
directory.
![Download zuliprc file](/static/images/integrations/google/calendar/001.png)
1. Run the `get-google-credentials` with this command:
python /usr/local/share/zulip/integrations/google/get-google-credentials
1. It should open up a browser and ask you for certain permissions. Give
Zulip access, and move on to the next step. If it doesn’t open a
browser, follow the instructions in the terminal window.
1. Now, all that’s left to do is to run the `gcal-bot` script, in the
same directory as the `get-google-credentials` script, with the
necessary parameters:
python /usr/local/share/zulip/integrations/google/gcal-bot --user foo@zulip.com
The `--user` flag specifies the user to send the reminder to.
1. Don’t close the terminal window with the bot running (you can use
`screen` if needed). You will only get reminders if the bot is still
running.
{!congrats.md!}
![Calendar demo](/static/images/integrations/google/calendar/003.png)
## Supported parameters
There are two optional flags that you can specify when running this
script:
* `--calendar`: This flag specifies the calendar to watch from the
user’s Google account. By default, this flag is set to a user’s
primary or default calendar. To specify a calendar, you need the
calendar ID which can be obtained by going to Google Calendar and
clicking on the wedge next to the calendar’s name. Click on settings
in **Calendar settings** in the drop down, and look for the **Calendar
Address** section. Copy the **Calendar ID** from the right side of the
page and use that as the value for this flag.
![Specify a calendar](/static/images/integrations/google/calendar/002.png)
* `--interval`: This flag specifies the interval of time - in
minutes - between receiving the reminder, and the actual event. For
example, an interval of 30 minutes would mean that you would receive a
reminder for an event 30 minutes before it is scheduled to occur.

67
templates/zerver/integrations/irc.md
View File

@@ -1,67 +0,0 @@
Mirror an IRC channel in Zulip!
### Install the bridge software
1. Clone the Zulip API repository, and install its dependencies.
```
git clone https://github.com/zulip/python-zulip-api.git
cd python-zulip-api
python3 ./tools/provision
```
This will create a new Python virtualenv. You'll run the bridge service
inside this virtualenv.
1. Activate the virtualenv by running the `source` command printed
at the end of the output of the previous step.
1. Go to the directory containing the bridge script if you haven't already done so
```
cd zulip/integrations/bridge_with_irc
```
1. Install the bridge dependencies in your virtualenv, by running:
```
pip install -r requirements.txt
```
### Configure the bridge
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.
1. Inside the virtualenv you created above, run:
```
python irc-mirror.py --irc-server=IRC_SERVER --channel=<CHANNEL> --nick-prefix=<NICK> \
--stream=<STREAM> [--topic=<TOPIC>] \
--site=<zulip.site> --user=<bot-email> \
--api-key=<api-key>
```
`--topic` is a Zulip topic, is optionally specified, defaults to "IRC".
Example command:
```
./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
```
**Congratulations! You're done!**
Your Zulip messages may look like:
![IRC message on Zulip](/static/images/integrations/irc/001.png)
Your IRC messages may look like:
![Zulip message on IRC](/static/images/integrations/irc/002.png)

71
templates/zerver/integrations/jira-plugin.md
View File

@@ -1,71 +0,0 @@
*If you are running Jira version 5.2 or greater, or using the hosted
Jira provided by Atlassian, we recommend using the
[web-hook method](./jira) above instead. This plugin supports older
versions of Jira.*
{!create-channel.md!}
### Plugin mechanism
{!download-python-bindings.md!}
#### Plugin installation
The Jira integration plugin requires two Jira plugins. Please install
the following plugins using the **Universal Plugin Manager** in your
Jira installation:
* [Script Runner Plugin][script-runner]
* [SSL Plugin][ssl-plugin]
[script-runner]: https://marketplace.atlassian.com/plugins/com.onresolve.jira.groovy.groovyrunner
[ssl-plugin]: https://marketplace.atlassian.com/plugins/com.atlassian.jira.plugin.jirasslplugin
#### SSL setup
As Zulip is using a StartCOM SSL certificate that is not recognized by
default in the Java installation shipped with Jira, you will need to
tell Jira about the certificate.
1. Navigate to **Administration > System > Configure SSL** and in the
**Import SSL Certificates** field, enter `{{ api_url }}`.
2. After clicking **Save Certificates**, follow the on-screen
instructions and restart Jira for it to recognize the proper
certificates.
#### Zulip integration
1. Copy the folder `integrations/jira/org/` (from the tarball you
downloaded above) to your Jira `classes` folder. For self-contained
Jira installations, this will be `atlassian-jira/WEB-INF/classes/`,
but this may be different in your deployment.
2. Edit the constants at the top of
`org/zulip/jira/ZulipListener.groovy` and fill them with the
appropriate values:
``` Python
String zulipEmail = "jira-notifications-bot@example.com"
String zulipAPIKey = "0123456789abcdef0123456789abcdef"
String zulipStream = "jira"
String issueBaseUrl = "https://jira.COMPANY.com/browse/"
```
3. On the **Administrators** page, navigate to
**Plugins > Other > Script Listeners**.
4. In the **Add Listener** section, click on the **Custom Listener**
option. Select the events you wish the Zulip integration to fire for,
and the projects you wish Zulip to be notified for.
5. In the **Name of groovy class** field, enter
`org.zulip.jira.ZulipListener`.
6. Click **Add Listener**, and Jira will now notify your Zulip of
changes to your issues! Updates from Jira will be sent to the stream
you've configured.
{!congrats.md!}
![Jira bot message](/static/images/integrations/jira/001.png)

95
templates/zerver/integrations/matrix.md
View File

@@ -1,95 +0,0 @@
Exchange messages between [matrix.org](https://matrix.org) and Zulip! If
you're looking to mirror an IRC channel in particular, we recommend our
[direct IRC integration](/integrations/doc/irc).
### Install the bridge software
1. Clone the Zulip API repository, and install its dependencies.
```
git clone https://github.com/zulip/python-zulip-api.git
cd python-zulip-api
python3 ./tools/provision
```
This will create a new Python virtualenv. You'll run the bridge service
inside this virtualenv.
1. Activate the virtualenv by running the `source` command printed
at the end of the output of the previous step.
1. Install the Matrix bridge software in your virtualenv, by running:
```
pip install -r zulip/integrations/bridge_with_matrix/requirements.txt
```
### Configure the bridge
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.
1. Inside the virtualenv you created above, run
```
python zulip/integrations/bridge_with_matrix/matrix_bridge.py \
--write-sample-config matrix_bridge.conf --from-zuliprc <path/to/zuliprc>
```
where `<path/to/zuliprc>` is the path to the `zuliprc` file you downloaded.
1. Create a user on [matrix.org](https://matrix.org/) or another matrix
server, preferably with a descriptive name like `zulip-bot`.
1. Edit `matrix_bridge.conf` to look like this:
```
[zulip]
email = bridge-bot@chat.zulip.org
api_key = aPiKeY
site = https://chat.zulip.org
stream = "stream name"
topic = "{{ integration_display_name }} mirror"
[matrix]
host = https://matrix.org
username = <your matrix username>
password = <your matrix password>
room_id = #room:matrix.org
```
The first three values should already be there; the rest you'll have to fill in.
Make sure **stream** is set to the stream the bot is
subscribed to.
{% if 'IRC' in integration_display_name %}
NOTE: For matrix.org, the `room_id` generally takes the form
`#<irc_network>_#<channel>:matrix.org`. You can see the format for
several popular IRC networks
[here](https://github.com/matrix-org/matrix-appservice-irc/wiki/Bridged-IRC-networks), under
the "Room alias format" column.
For example, the `room_id` for the `#zulip-test` channel on freenode is
`#freenode_#zulip-test:matrix.org`.
{% endif %}
1. Run the following command to start the matrix bridge:
```
python zulip/integrations/bridge_with_matrix/matrix_bridge.py -c matrix_bridge.conf
```
!!! tip ""
You can customize the message formatting by
editing the variables `MATRIX_MESSAGE_TEMPLATE` and `ZULIP_MESSAGE_TEMPLATE`
in `zulip/integrations/bridge_with_matrix/matrix_bridge.py`.
**Note**: There are a handful of
[IRC channels](https://github.com/matrix-org/matrix-appservice-irc/wiki/Channels-from-which-the-IRC-bridge-is-banned)
that have temporarily banned the Matrix.org IRC bridge.
You can't currently mirror those channels using this integration.

86
templates/zerver/integrations/mercurial.md
View File

@@ -1,86 +0,0 @@
Get Zulip notifications when you `hg push`!
1. {!create-channel.md!}
1. {!create-an-incoming-webhook.md!}
1. {!download-python-bindings.md!}
1. Edit the `hg/.hgrc` configuration file for this default Mercurial
repository and add the following sections, using the credentials for
your Mercurial bot and setting the appropriate path to the integration
hook if it installs in a different location on this system:
[hooks]
changegroup = python:zulip_changegroup.hook
[zulip]
email = "hg-bot@example.com"
api_key = "0123456789abcdefg"
stream = "commits"
site = {{ api_url }}
1. Add the directory where the `zulip_changegroup.py` script was
installed to the environment variable `PYTHONPATH`. For example, if
you installed the Zulip Python bindings at the system level, it'd be:
export PYTHONPATH=/usr/local/share/zulip/integrations/hg:$PYTHONPATH
That’s all it takes for the basic setup! On the next `hg push`, you’ll
get a Zulip update for the changeset.
### More configuration options
The Mercurial integration also supports:
- linking to changelog and revision URLs for your repository’s web UI
- branch whitelists and blacklists
#### Web repository links
If you’ve set up your repository to be [browsable via the web][1],
add a `web_url` configuration option to the `zulip` section of your
default `.hg/hgrc` to get changelog and revision links in your Zulip
notifications:
[zulip]
email = "hg-bot@example.com"
api_key = "0123456789abcdefg"
stream = "commits"
web_url = "http://hg.example.com:8000/"
site = {{ api_url }}
[1]: https://www.mercurial-scm.org/wiki/QuickStart#Network_support
#### Branch whitelists and blacklists
By default, this integration will send Zulip notifications for
changegroup events for all branches. If you’d prefer to only receive
Zulip notifications for specified branches, add a `branches`
configuration option to the `zulip` section of your default `.hg/hgrc`,
containing a comma-separated list of the branches that should produce
notifications:
[zulip]
email = "hg-bot@example.com"
api_key = "0123456789abcdefg"
stream = "commits"
branches = "prod,default"
You can also exclude branches that you don’t want to cause
notifications. To do so, add an `ignore_branches` configuration option
to the `zulip` section of your default `.hg/hgrc`, containing a
comma-separated list of the branches that should be ignored:
[zulip]
email = "hg-bot@example.com"
api_key = "0123456789abcdefg"
stream = "commits"
ignore_branches = "noisy,even-more-noisy"
When team members push new changesets with `hg push`, you’ll get a
Zulip notification.
{!congrats.md!}
![Mercurial bot message](/static/images/integrations/hg/001.png)

63
templates/zerver/integrations/nagios.md
View File

@@ -1,63 +0,0 @@
1. {!create-channel.md!}
1. {!download-python-bindings.md!}
1. {!create-an-incoming-webhook.md!}
1. Next, open `integrations/nagios/zuliprc.example` in your favorite
editor, and change the following lines to specify the email address
and API key for your Nagios bot, saving it to `/etc/nagios4/zuliprc`
on your Nagios server:
```
[api]
email = NAGIOS_BOT_EMAIL_ADDRESS
key = NAGIOS_BOT_API_KEY
site = {{ api_url }}
```
1. Copy `integrations/nagios/zulip_nagios.cfg` to `/etc/nagios4/conf.d`
on your Nagios server.
1. Finally, add `zulip` to the `members` list for one or more of the
contact groups in the `CONTACT GROUPS` section of
`/etc/nagios4/conf.d/contacts.cfg`, doing something like:
```
define contactgroup {
contactgroup_name admins
alias Nagios Administrators
members monitoring, zulip
}
```
1. Once you’ve done that, reload your Nagios configuration using
`/etc/init.d/nagios4 reload`.
1. When your Nagios system makes an alert, you’ll see a message like the
following, to the stream `nagios` (to change this, edit the arguments
to `nagios-notify-zulip` in `/etc/nagios4/conf.d/zulip_nagios.cfg`)
with a topic indicating the service with an issue.
{!congrats.md!}
![Nagios bot message](/static/images/integrations/nagios/001.png)
### Testing
If you have [external commands enabled in Nagios][1],
you can generate a test notice from your Nagios instance by
using the `Send custom service notification` command in the
`Service Commands` section of any individual service’s page
on your Nagios instance.
[1]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/extcommands.html
### Troubleshooting
You can confirm whether you’ve correctly configured Nagios to run the
Zulip plugin by looking for `SERVICE NOTIFICATION` lines mentioning
zulip in `/var/log/nagios4/nagios.log`. You can confirm whether you’ve
configured the Zulip plugin code correctly by running
`/usr/local/share/zulip/integrations/nagios/nagios-notify-zulip`
directly.

43
templates/zerver/integrations/openshift.md
View File

@@ -1,43 +0,0 @@
This integration sends a notification every time a deployment is made
in an OpenShift instance.
1. {!create-channel.md!}
1. {!download-python-bindings.md!}
1. Then, create a new commit including all the changes made to the
repository, and push it to your app.
1. After that, connect to the application through SSH. If you don’t know
how to do this, log in to your OpenShift Online account, go to your
application’s dashboard, and click **Want to log in to your
application?**. There you’ll find the app’s SSH user, address, and
further information on SSH, in case you need it.
![Connecting to application](/static/images/integrations/openshift/002.png)
1. {!change-zulip-config-file.md!}
1. You can also specify which pushes will result in notifications and to
what stream the notifications will be sent by modifying the
`deployment_notice_destination` function in
`zulip_openshift_config.py`. By default, deployments triggered by
commits pushed to the `main`, `master`, and `test-post-receive` branches will
result in a notification to stream `deployments`.
1. Save the file, and symlink
`$OPENSHIFT_PYTHON_DIR/virtenv/share/zulip/integrations/openshift/post-receive`
into the `~/app-root/repo/.openshift/action_hooks` directory.
1. Whenever you make a push to the `main` branch of your application’s
repository (or whichever branch you configured above), or if you force
a deployment, the Zulip OpenShift plugin will send an automated
notification.
{!congrats.md!}
![OpenShift integration message](/static/images/integrations/openshift/001.png)
### Testing
You can test the plugin without changing your `main` branch by pushing to the `test-post-receive` branch.

48
templates/zerver/integrations/perforce.md
View File

@@ -1,48 +0,0 @@
Zulip supports integration with Perforce as a [trigger][1]
that fires once a changelist is submitted and committed.
[1]: https://www.perforce.com/manuals/p4sag/Content/P4SAG/chapter.scripting.html
1. {!download-python-bindings.md!}
1. The Perforce trigger will be installed to a location like
`/usr/local/share/zulip/integrations/perforce`.
1. {!change-zulip-config-file.md!}
1. If you have a P4Web viewer set up, you may change `P4_WEB`
to point at the base URL of the server. If this is configured,
then the changelist number of each commit will be converted to
a hyperlink that displays the commit details on P4Web.
1. Edit your [trigger table][2] with `p4 triggers` and add an entry
something like the following:
notify_zulip change-commit //depot/... "/usr/local/share/zulip/integrations/perforce/zulip_change-commit.py %change% %changeroot%"
[2]: https://www.perforce.com/manuals/p4sag/Content/P4SAG/chapter.scripting.html#d0e14583
1. By default, this hook will send to streams of the form
`depot_subdirectory-commits`. So, a changelist that modifies
files in `//depot/foo/bar/baz` will result in a message to
stream `foo-commits`. Messages about changelists that modify
files in the depot root or files in multiple direct subdirectories
of the depot root will be sent to `depot-commits`.
If you'd prefer different behavior, such as all commits across your
depot going to one stream, change it now in `zulip_perforce_config.py`.
Make sure that everyone interested in getting these post-commit Zulips
is subscribed to the relevant streams!
1. By default, this hook will send a message to Zulip even if the
destination stream does not yet exist. Messages to nonexistent
streams prompt the Zulip Notification Bot to inform the bot's
owner by direct message that they may wish to create the stream.
If this behaviour is undesirable, for example with a large and busy
Perforce server, change the `ZULIP_IGNORE_MISSING_STREAM`
variable in `zulip_perforce_config.py` to `True`.
This will change the hook's behaviour to first check whether the
destination stream exists and silently drop messages if it does not.
{!congrats.md!}
![Perforce notification bot message](/static/images/integrations/perforce/001.png)

26
templates/zerver/integrations/rss.md
View File

@@ -1,26 +0,0 @@
Get service alerts, news, and new blog posts right in Zulip with our
RSS integration!
!!! tip ""
Note that [the Zapier integration][1] is usually a simpler way to
integrate RSS with Zulip.
[1]: ./zapier
1. {!create-channel.md!}
1. {!create-an-incoming-webhook.md!}
1. {!download-python-bindings.md!}
1. The RSS integration will be installed to a location like
`/usr/local/share/zulip/integrations/rss/rss-bot`.
1. Follow the instructions in the `rss-bot` script for configuring the
bot, adding your subscriptions, and setting up a cron job to run
the bot.
{!congrats.md!}
![RSS bot message](/static/images/integrations/rss/001.png)

27
templates/zerver/integrations/svn.md
View File

@@ -1,27 +0,0 @@
It is easy to send Zulips on SVN commits, by configuring a
post-commit hook. To do this:
1. {!create-channel.md!}
1. {!download-python-bindings.md!}
1. Install `pysvn`. On Linux, you can install the `python-svn`
package. On other platforms, you can install a binary or from
source by following the [instructions on the pysvn website][1].
[1]: http://pysvn.tigris.org/project_downloads.html
1. {!change-zulip-config-file.md!}
1. Copy `integrations/svn/zulip_svn_config.py` and
`integrations/svn/post-commit` from the API bindings directory
to the `hooks` subdirectory of your SVN repository.
1. The default stream used by this post-commit hook is `commits`; if
you’d prefer a different stream, change it now in
`zulip_svn_config.py`. Make sure that everyone interested in getting
these post-commit Zulips is subscribed to that stream!
{!congrats.md!}
![SVN commit bot message](/static/images/integrations/svn/001.png)

43
templates/zerver/integrations/trac.md
View File

@@ -1,43 +0,0 @@
1. {!create-channel.md!}
1. {!download-python-bindings.md!}
1. {!change-zulip-config-file.md!}
1. Also, change the following lines:
```
STREAM_FOR_NOTIFICATIONS = "trac"
TRAC_BASE_TICKET_URL = "https://trac.example.com/ticket"
```
1. Set `STREAM_FOR_NOTIFICATIONS` to the name of the stream
you'd like the notifications to be sent to.
1. Copy `integrations/trac/zulip_trac.py` and
`integrations/trac/zulip_trac_config.py` into your Trac installation’s
`plugins/` subdirectory. Once you’ve done that, edit your Trac
installation’s `conf/trac.ini` to add `zulip_trac` to the
`[components]` section, as follows:
```
[components]
zulip_trac = enabled
```
1. You may then need to restart Trac (or Apache) so that Trac will load
our plugin.
1. When people open new tickets (or edit existing tickets), notifications
will be sent to the stream `trac` (or whatever you
configured above) with a topic that matches the ticket name.
{!congrats.md!}
![Trac bot message](/static/images/integrations/trac/001.png)
### Additional trac configuration
After using the plugin for a while, you may want to customize which
changes to tickets result in a Zulip notification using the
`TRAC_NOTIFY_FIELDS` setting in `zulip_trac_config.py`.

8
tools/lib/provision_inner.py
View File

@@ -31,7 +31,10 @@ from scripts.lib.zulip_tools import (
run_as_root,
write_new_digest,
)
from tools.setup.generate_zulip_bots_static_files import generate_zulip_bots_static_files
from tools.setup.generate_bots_integrations_static_files import (
generate_pythonapi_integrations_static_files,
generate_zulip_bots_static_files,
)
from version import PROVISION_VERSION
VENV_PATH = os.path.join(ZULIP_PATH, ".venv")
@@ -270,8 +273,9 @@ def main(options: argparse.Namespace) -> int:
# packages.
run(["tools/setup/emoji/build_emoji"])
# copy over static files from the zulip_bots package
# copy over static files from the zulip_bots and integrations packages
generate_zulip_bots_static_files()
generate_pythonapi_integrations_static_files()
if options.is_force or need_to_run_build_pygments_data():
run(["tools/setup/build_pygments_data"])

25
tools/setup/generate_zulip_bots_static_files.py → tools/setup/generate_bots_integrations_static_files.py
View File

@@ -11,9 +11,33 @@ from scripts.lib.setup_path import setup_path
setup_path()
import integrations
from zulip_bots.lib import get_bots_directory_path
def generate_pythonapi_integrations_static_files() -> None:
integrations_dir = "static/generated/integrations"
if os.path.isdir(integrations_dir):
# delete old static files, they could be outdated
shutil.rmtree(integrations_dir)
os.makedirs(integrations_dir, exist_ok=True)
package_integrations_dir = os.path.dirname(os.path.abspath(integrations.__file__))
def copy_integrations_data(integration_names: list[str]) -> None:
# The integration name as used in zulip/python-zulip-api.
for name in integration_names:
src_dir = os.path.join(package_integrations_dir, name)
dst_dir = os.path.join(integrations_dir, name)
doc_path = os.path.join(src_dir, "doc.md")
if os.path.isfile(doc_path):
os.makedirs(dst_dir, exist_ok=True)
shutil.copyfile(doc_path, os.path.join(dst_dir, "doc.md"))
copy_integrations_data(os.listdir(package_integrations_dir))
def generate_zulip_bots_static_files() -> None:
bots_dir = "static/generated/bots"
if os.path.isdir(bots_dir):
@@ -49,4 +73,5 @@ def generate_zulip_bots_static_files() -> None:
if __name__ == "__main__":
generate_pythonapi_integrations_static_files()
generate_zulip_bots_static_files()

4
tools/update-prod-static
View File

@@ -33,8 +33,8 @@ setup_node_modules(production=True)
# Build emoji
run(["./tools/setup/emoji/build_emoji"])
# Copy over static files from the zulip_bots package
run(["./tools/setup/generate_zulip_bots_static_files.py"])
# Copy over static files from the zulip_bots and integrations packages
run(["./tools/setup/generate_bots_integrations_static_files.py"])
# Build pygments data
run(["./tools/setup/build_pygments_data"])

8
uv.lock generated
View File

@@ -4974,14 +4974,14 @@ requires-dist = [{ name = "typing-extensions" }]
[[package]]
name = "zulip"
version = "0.9.0"
source = { url = "https://github.com/zulip/python-zulip-api/archive/0.9.0.zip", subdirectory = "zulip" }
source = { url = "https://github.com/zulip/python-zulip-api/archive/9e131ac626976b9c3da6c11b6365b4939656f7c3.zip", subdirectory = "zulip" }
dependencies = [
{ name = "click" },
{ name = "distro" },
{ name = "requests" },
{ name = "typing-extensions" },
]
sdist = { hash = "sha256:71ea94192f1a0de1c45fd177e827b65fe4970c4fc8565991fd066b4de77eaccb" }
sdist = { hash = "sha256:4d5adc0d3a1a638138c416a426e161bf4a804c97819ffaad87fbc1320a5066de" }
[package.metadata]
requires-dist = [
@@ -5359,7 +5359,7 @@ dev = [
{ name = "virtualenv-clone" },
{ name = "werkzeug", specifier = "<3.1.2" },
{ name = "zulint", url = "https://github.com/zulip/zulint/archive/9be0a32bf75a9d8738b005f0b880567fff64e943.zip" },
{ name = "zulip", url = "https://github.com/zulip/python-zulip-api/archive/0.9.0.zip", subdirectory = "zulip" },
{ name = "zulip", url = "https://github.com/zulip/python-zulip-api/archive/9e131ac626976b9c3da6c11b6365b4939656f7c3.zip", subdirectory = "zulip" },
{ name = "zulip-bots", url = "https://github.com/zulip/python-zulip-api/archive/0.9.0.zip", subdirectory = "zulip_bots" },
{ name = "zxcvbn" },
]
@@ -5443,7 +5443,7 @@ prod = [
{ name = "uwsgi" },
{ name = "virtualenv-clone" },
{ name = "werkzeug", specifier = "<3.1.2" },
{ name = "zulip", url = "https://github.com/zulip/python-zulip-api/archive/0.9.0.zip", subdirectory = "zulip" },
{ name = "zulip", url = "https://github.com/zulip/python-zulip-api/archive/9e131ac626976b9c3da6c11b6365b4939656f7c3.zip", subdirectory = "zulip" },
{ name = "zulip-bots", url = "https://github.com/zulip/python-zulip-api/archive/0.9.0.zip", subdirectory = "zulip_bots" },
{ name = "zxcvbn" },
]

2
version.py
View File

@@ -49,4 +49,4 @@ API_FEATURE_LEVEL = 371 # Last bumped for Zulip 10.0 release.
# historical commits sharing the same major version, in which case a
# minor version bump suffices.
PROVISION_VERSION = (321, 0) # bumped 2025-03-14 to upgrade JavaScript dependencies
PROVISION_VERSION = (321, 1) # bumped 2025-03-26 to generate static/generated/integrations files.

15
zerver/lib/integrations.py
View File

@@ -190,6 +190,8 @@ class BotIntegration(Integration):
class PythonAPIIntegration(Integration):
DEFAULT_DOC_PATH = "{directory_name}/doc.md"
def __init__(
self,
name: str,
@@ -203,6 +205,15 @@ class PythonAPIIntegration(Integration):
stream_name: str | None = None,
legacy: bool = False,
) -> None:
if directory_name is None:
directory_name = name
self.directory_name = directory_name
# Assign before super(), to use self.directory_name instead of self.name
if doc is None:
doc = self.DEFAULT_DOC_PATH.format(directory_name=self.directory_name)
self.doc = doc
super().__init__(
name,
categories,
@@ -215,10 +226,6 @@ class PythonAPIIntegration(Integration):
legacy=legacy,
)
if directory_name is None:
directory_name = name
self.directory_name = directory_name
class WebhookIntegration(Integration):
DEFAULT_FUNCTION_PATH = "zerver.webhooks.{name}.view.api_{name}_webhook"

4
zproject/computed_settings.py
View File

@@ -680,6 +680,10 @@ default_template_engine_settings.update(
os.path.join(DEPLOY_ROOT, "templates"),
# The webhook integration templates
os.path.join(DEPLOY_ROOT, "zerver", "webhooks"),
# The python-zulip-api:integrations package templates
# Keep above the zulip_bots templates to override bots with the same names
# (e.g., the Jira plugin doc and the Jira bot both use "jira/doc.md").
os.path.join("static" if DEBUG else STATIC_ROOT, "generated", "integrations"),
# The python-zulip-api:zulip_bots package templates
os.path.join("static" if DEBUG else STATIC_ROOT, "generated", "bots"),
],