integration-docs: Update the Google Calendar integration doc.

Author: Niloth-p

zulip/integrations/google/doc.md

@@ -1,72 +1,180 @@
-Get Google Calendar reminders in Zulip! This is a great way to see
-your reminders directly in your Zulip feed.
+# Zulip Google Calendar integration
 
-1.  {!download-python-bindings.md!}
+Get Zulip notifications for your Google Calendar events!
 
-    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.
+### Create Zulip bot for Google Calendar notifications
 
-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.
+{start_tabs}
 
-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.  {!create-a-generic-bot.md!}
 
-1.  In Zulip, go to your click on the cog in the top right corner, and
-    then clicking on **Personal settings**.
+1.  [Download your bot's `zuliprc` file][download-zuliprc], and save it as
+    `.zuliprc` in your `~/` directory.
 
-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]: /api/configuring-python-bindings#download-a-zuliprc-file
 
-    ![Download zuliprc file](/static/images/integrations/google/calendar/001.png)
+1.  Optionally, to configure the bot, add a **`google-calendar`** section to
+    the `.zuliprc` file, like below:
 
-1.  Run the `get-google-credentials` with this command:
+    ```
+    [google-calendar]
+    interval=30
+    channel=core-team
+    topic=scheduled events
+    ```
 
-        python /usr/local/share/zulip/integrations/google/get-google-credentials
+    See [configuration options](#configuration-options) for the list of
+    available options.
 
-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.
+{end_tabs}
 
-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:
+### Setup Google OAuth Client ID
 
-        python /usr/local/share/zulip/integrations/google/gcal-bot --user [email protected]
+{start_tabs}
 
-    The `--user` flag specifies the user to send the reminder to.
+!!! tip ""
 
-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.
+    A free Google account is sufficient for this integration; a Google
+    service account is not required.
 
-{!congrats.md!}
+1.  In the Google Cloud console, go to
+    **Menu > Google Auth platform > [Branding][branding-menu]**. If you see
+    a message that says **Google Auth platform not configured yet**, click
+    **Get Started**, and fill the form with the following details.
 
-![Calendar demo](/static/images/integrations/google/calendar/003.png)
+    - Under **App Information**, set **App name** to a name of your choice.
+      Set **User support email** to your email address from the dropdown.
+      Click **Next**.
+    - Under **Audience**, select **External**, and click **Next**.
+    - Under **Contact Information**, enter your email address, and click
+      **Next**.
+    - Under **Finish**, review the
+      **Google API Services User Data Policy** and if you agree, select
+      **I agree**. Click **Continue**, and click **Create**.
 
-## Supported parameters
+1.  Go to the **[Clients][clients-menu]** tab. Click **Create Client**.
+    Select **Application type > Desktop app**. Set **Name** to a name of
+    your choice, such as `Zulip`, and click **Create**. Save the downloaded
+    JSON file as `client_secret.json` in your `~/` directory.
 
-There are two optional flags that you can specify when running this
-script:
+1.  Go to the **[Audience][audience-menu]** tab. Under **Test users**, click **+ Add Users**.
+    Enter the email address corresponding to your Google Calendar, and click
+    **Save**.
 
-* `--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.
+[branding-menu]: https://console.cloud.google.com/auth/branding
+[clients-menu]: https://console.cloud.google.com/auth/clients
+[audience-menu]: https://console.cloud.google.com/auth/audience
 
-![Specify a calendar](/static/images/integrations/google/calendar/002.png)
+{end_tabs}
 
-* `--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.
+### Run the integration script
+
+{start_tabs}
+
+1.  Download and
+    [install the Zulip Python API](/api/installation-instructions) with:
+
+    `pip install zulip`
+
+1.  Install the requirements for the integration script with:
+
+    `python {{ integration_path }} --provision`
+
+1.  Run the integration script with:
+
+    `python {{ integration_path }}`
+
+    Authorize access in the browser window that opens, to allow the Zulip
+    bot to view your Calendar. If you've set `noauth_local_webserver` to
+    true, follow the terminal prompts instead, and paste the resulting
+    authorization code.
+
+1.  Optionally, pass commandline arguments to configure the integration. The
+    commandline arguments override the corresponding settings in the
+    `.zuliprc` file.
+
+    `python {{ integration_path }} --interval 30 --channel core-team --topic "scheduled events"`
+
+    See [configuration options](#configuration-options) for the list of
+    available options.
+
+1.  You will get notifications as long as the terminal session with the bot
+    remains open. Consider using `screen` to run the bot in the background.
+
+!!! tip ""
+
+    Newly added calendar events may take up to 10 minutes to generate
+    notifications.
+
+{end_tabs}
+
+### Configure the integration
+
+The integration can be configured by:
+
+- Passing command line arguments to the integration script.
+- Editing the `google-calendar` section of the `zuliprc` file.
+
+The configuration settings in `zuliprc` will be overridden by the
+corresponding command line options, if both are used.
+
+### Configuration options
+
+The integration script accepts the following configuration options:
+
+- `interval`: How many minutes in advance you want reminders delivered.
+  The default value is 30 minutes.
+
+- `channel`: The name of the Zulip channel you want to receive
+  notifications in. By default, messages are sent as direct messages to the
+  bot's owner.
+
+- `topic`: The name of the Zulip topic you want to receive notifications
+  in. This option is ignored if the `channel` option is unspecified. If the
+  `channel` option is specified, the default topic is "calendar-reminders".
+
+- `client-secret-file`: The path to the file containing the client secret.
+  By default, the client secret file is assumed to be at
+  `~/client_secret.json`.
+
+- `tokens-file`: The path to the file where the OAuth tokens are stored. By
+  default, the tokens file is generated at `~/google-tokens.json` when the
+  integration is first run, and is rewritten every hour.
+
+- `noauth-local-webserver`: This option stops the integration script from
+  starting a local webserver for receiving OAuth tokens. The default
+  authorization process runs a local web server, which requires a browser on
+  the same machine. For non-interactive environments and machines without
+  browser access, e.g., remote servers, this option allows manual
+  authorization. The authorization URL is printed, which the user can copy
+  into a browser, copy the resulting authorization code, and paste back into
+  the command line.
+
+- `calendar`: The `calendar ID` of the Google calendar to get events from.
+  By default, the `primary` calendar is used.
+
+- `format-message`: The template for the message that is sent to Zulip. This
+  Python f-string supports Markdown, and can use the following variables:
+  `start`, `end`, `title`, `description`, `calendar_link`, `location`,
+  `google_meet_link`.
+
+    !!! warn ""
+
+        **Note:** The `title`, `description`, `location`, and
+        `google_meet_link` variables are optional for Google Calendar
+        events, and hence may be empty. Empty fields are displayed as
+        "{No title}", "{No description}", "{No location}", and "{No link}"
+        in the message template.
+
+    The default message template takes the following form when all the event
+    field variables are non-empty.
+
+    `The event [{title}]({calendar_link}), at {location}, is from {start} to {end}.\n> {description}\n\n[Join call]({google_meet_link}).`
+
+### Related documentation
+
+- [Google's documentation on configuring the OAuth consent screen][consent-screen]
+- [Google's documentation on setting up OAuth Client IDs][client-secret]
+
+[consent-screen]: https://developers.google.com/workspace/calendar/api/quickstart/python#configure_the_oauth_consent_screen
+[client-secret]: https://developers.google.com/workspace/calendar/api/quickstart/python#authorize_credentials_for_a_desktop_application