integration-docs: Migrate docs closer to their source code.

zulip/integrations/bridge_with_irc/doc.md

@@ -0,0 +1,67 @@
+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" [email protected] \
+--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)

zulip/integrations/bridge_with_matrix/doc.md

@@ -0,0 +1,95 @@
+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 = [email protected]
+    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.

zulip/integrations/codebase/doc.md

@@ -0,0 +1,53 @@
+# 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)

zulip/integrations/git/doc.md

@@ -0,0 +1,31 @@
+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)

zulip/integrations/google/doc.md

@@ -0,0 +1,72 @@
+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 [email protected]
+
+    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.