From b2910aa05cca4dfec569fd717b1bbd32506bd9b3 Mon Sep 17 00:00:00 2001 From: Niloth P <20315308+Niloth-p@users.noreply.github.com> Date: Wed, 12 Mar 2025 12:04:27 +0530 Subject: [PATCH] integration-docs: Migrate PythonAPIIntegration docs. 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. --- pyproject.toml | 3 +- static/.gitignore | 2 + templates/zerver/integrations/codebase.md | 53 ----------- templates/zerver/integrations/git.md | 31 ------ .../zerver/integrations/google-calendar.md | 72 -------------- templates/zerver/integrations/irc.md | 67 ------------- templates/zerver/integrations/jira-plugin.md | 71 -------------- templates/zerver/integrations/matrix.md | 95 ------------------- templates/zerver/integrations/mercurial.md | 86 ----------------- templates/zerver/integrations/nagios.md | 63 ------------ templates/zerver/integrations/openshift.md | 43 --------- templates/zerver/integrations/perforce.md | 48 ---------- templates/zerver/integrations/rss.md | 26 ----- templates/zerver/integrations/svn.md | 27 ------ templates/zerver/integrations/trac.md | 43 --------- tools/lib/provision_inner.py | 8 +- ...enerate_bots_integrations_static_files.py} | 25 +++++ tools/update-prod-static | 4 +- uv.lock | 8 +- version.py | 2 +- zerver/lib/integrations.py | 15 ++- zproject/computed_settings.py | 4 + 22 files changed, 57 insertions(+), 739 deletions(-) delete mode 100644 templates/zerver/integrations/codebase.md delete mode 100644 templates/zerver/integrations/git.md delete mode 100644 templates/zerver/integrations/google-calendar.md delete mode 100644 templates/zerver/integrations/irc.md delete mode 100644 templates/zerver/integrations/jira-plugin.md delete mode 100644 templates/zerver/integrations/matrix.md delete mode 100644 templates/zerver/integrations/mercurial.md delete mode 100644 templates/zerver/integrations/nagios.md delete mode 100644 templates/zerver/integrations/openshift.md delete mode 100644 templates/zerver/integrations/perforce.md delete mode 100644 templates/zerver/integrations/rss.md delete mode 100644 templates/zerver/integrations/svn.md delete mode 100644 templates/zerver/integrations/trac.md rename tools/setup/{generate_zulip_bots_static_files.py => generate_bots_integrations_static_files.py} (61%) diff --git a/pyproject.toml b/pyproject.toml index d673b82bb5..850221aa01 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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.*", diff --git a/static/.gitignore b/static/.gitignore index ff46c39f49..34d6ab6186 100644 --- a/static/.gitignore +++ b/static/.gitignore @@ -5,5 +5,7 @@ # Copied zulip_bots package /generated/bots/ +# Copied integrations package +/generated/integrations/ # From emoji /generated/emoji diff --git a/templates/zerver/integrations/codebase.md b/templates/zerver/integrations/codebase.md deleted file mode 100644 index ce42f2c508..0000000000 --- a/templates/zerver/integrations/codebase.md +++ /dev/null @@ -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) diff --git a/templates/zerver/integrations/git.md b/templates/zerver/integrations/git.md deleted file mode 100644 index ffd281f0a7..0000000000 --- a/templates/zerver/integrations/git.md +++ /dev/null @@ -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) diff --git a/templates/zerver/integrations/google-calendar.md b/templates/zerver/integrations/google-calendar.md deleted file mode 100644 index e9a21b3afb..0000000000 --- a/templates/zerver/integrations/google-calendar.md +++ /dev/null @@ -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. diff --git a/templates/zerver/integrations/irc.md b/templates/zerver/integrations/irc.md deleted file mode 100644 index e204754de8..0000000000 --- a/templates/zerver/integrations/irc.md +++ /dev/null @@ -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= --nick-prefix= \ - --stream= [--topic=] \ - --site= --user= \ - --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) diff --git a/templates/zerver/integrations/jira-plugin.md b/templates/zerver/integrations/jira-plugin.md deleted file mode 100644 index cd11876fed..0000000000 --- a/templates/zerver/integrations/jira-plugin.md +++ /dev/null @@ -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) diff --git a/templates/zerver/integrations/matrix.md b/templates/zerver/integrations/matrix.md deleted file mode 100644 index 57dd395617..0000000000 --- a/templates/zerver/integrations/matrix.md +++ /dev/null @@ -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 - ``` - - where `` 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 = - 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 - `#_#: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. diff --git a/templates/zerver/integrations/mercurial.md b/templates/zerver/integrations/mercurial.md deleted file mode 100644 index 569a4c5f03..0000000000 --- a/templates/zerver/integrations/mercurial.md +++ /dev/null @@ -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) diff --git a/templates/zerver/integrations/nagios.md b/templates/zerver/integrations/nagios.md deleted file mode 100644 index c0f342a6f5..0000000000 --- a/templates/zerver/integrations/nagios.md +++ /dev/null @@ -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. diff --git a/templates/zerver/integrations/openshift.md b/templates/zerver/integrations/openshift.md deleted file mode 100644 index 7a7a2a8df1..0000000000 --- a/templates/zerver/integrations/openshift.md +++ /dev/null @@ -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. diff --git a/templates/zerver/integrations/perforce.md b/templates/zerver/integrations/perforce.md deleted file mode 100644 index d4ae2c1f54..0000000000 --- a/templates/zerver/integrations/perforce.md +++ /dev/null @@ -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) diff --git a/templates/zerver/integrations/rss.md b/templates/zerver/integrations/rss.md deleted file mode 100644 index 967d942f56..0000000000 --- a/templates/zerver/integrations/rss.md +++ /dev/null @@ -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) diff --git a/templates/zerver/integrations/svn.md b/templates/zerver/integrations/svn.md deleted file mode 100644 index e4e3fbcae1..0000000000 --- a/templates/zerver/integrations/svn.md +++ /dev/null @@ -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) diff --git a/templates/zerver/integrations/trac.md b/templates/zerver/integrations/trac.md deleted file mode 100644 index 165f328346..0000000000 --- a/templates/zerver/integrations/trac.md +++ /dev/null @@ -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`. diff --git a/tools/lib/provision_inner.py b/tools/lib/provision_inner.py index 17e2e790c0..de8630d496 100755 --- a/tools/lib/provision_inner.py +++ b/tools/lib/provision_inner.py @@ -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"]) diff --git a/tools/setup/generate_zulip_bots_static_files.py b/tools/setup/generate_bots_integrations_static_files.py similarity index 61% rename from tools/setup/generate_zulip_bots_static_files.py rename to tools/setup/generate_bots_integrations_static_files.py index 2e545b0cb2..988d9874b5 100755 --- a/tools/setup/generate_zulip_bots_static_files.py +++ b/tools/setup/generate_bots_integrations_static_files.py @@ -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() diff --git a/tools/update-prod-static b/tools/update-prod-static index 4aa0b80b21..61259b8ffd 100755 --- a/tools/update-prod-static +++ b/tools/update-prod-static @@ -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"]) diff --git a/uv.lock b/uv.lock index c65d1ae750..872b608df6 100644 --- a/uv.lock +++ b/uv.lock @@ -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" }, ] diff --git a/version.py b/version.py index 774248eeac..4301f45014 100644 --- a/version.py +++ b/version.py @@ -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. diff --git a/zerver/lib/integrations.py b/zerver/lib/integrations.py index e7fa720320..d724a73489 100644 --- a/zerver/lib/integrations.py +++ b/zerver/lib/integrations.py @@ -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" diff --git a/zproject/computed_settings.py b/zproject/computed_settings.py index 7811c43d28..68aae82505 100644 --- a/zproject/computed_settings.py +++ b/zproject/computed_settings.py @@ -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"), ],