Merge pull request #263 from ballerina-platform/dev

Tweak documentation

.github/workflows/dev-stage-release.yml

@@ -19,4 +19,4 @@ jobs:
     secrets: inherit
     with:
       environment: ${{ github.event.inputs.environment }}
-      additional-publish-flags: "-x :googleapis.gmail-examples:build -Pgroups=mock"
+      additional-publish-flags: "-x :googleapis.gmail-examples:build"

README.md

@@ -9,9 +9,9 @@
 
 [Gmail](https://blog.google/products/gmail/) is a widely-used email service provided by Google LLC, enabling users to send and receive emails over the internet.
 
-The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints.
+The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1).
 
-## Set up Gmail API
+## Set up guide
 
 To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/).
 
@@ -127,21 +127,18 @@ gmail:MessageRequest message = {
 gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
 ```
 
-## Samples
+## Examples
 
-The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [samples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels.
+The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels.
 
-1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal)
-    Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
+1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
 
-2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal)
-    Automatically send emails for scheduled maintenance breaks.
+2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks
 
-3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal)
-    Automate fetching unread emails from the Inbox and send personalized responses to customers.
+3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses.
 
-4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal)
-    Use the Gmail API to search for email threads based on a specific query.
+4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads)
+    Search for email threads based on a specified query.
 
 ## Issues and projects
 

ballerina/Module.md

@@ -1,10 +1,10 @@
-# Overview
+## Overview
 
 [Gmail](https://blog.google/products/gmail/) is a widely-used email service provided by Google LLC, enabling users to send and receive emails over the internet.
 
-The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints.
+The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1).
 
-## Set up Gmail API
+## Set up guide
 
 To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/).
 
@@ -120,18 +120,15 @@ gmail:MessageRequest message = {
 gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
 ```
 
-## Samples
+## Examples
 
-The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [samples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels.
+The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels.
 
-1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal)
-    Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
+1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
 
-2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal)
-    Automatically send emails for scheduled maintenance breaks.
+2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks
 
-3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal)
-    Automate fetching unread emails from the Inbox and send personalized responses to customers.
+3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses.
 
-4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal)
-    Use the Gmail API to search for email threads based on a specific query.
+4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads)
+    Search for email threads based on a specified query.

ballerina/Package.md

@@ -1,10 +1,10 @@
-# Package overview
+## Package overview
 
 [Gmail](https://blog.google/products/gmail/) is a widely-used email service provided by Google LLC, enabling users to send and receive emails over the internet.
 
-The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints.
+The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1).
 
-## Set up Gmail API
+## Set up guide
 
 To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/).
 
@@ -120,21 +120,18 @@ gmail:MessageRequest message = {
 gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
 ```
 
-## Samples
+## Examples
 
-The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [samples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels.
+The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels.
 
-1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal)
-    Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
+1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
 
-2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal)
-    Automatically send emails for scheduled maintenance breaks.
+2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks
 
-3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal)
-    Automate fetching unread emails from the Inbox and send personalized responses to customers.
+3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses.
 
-4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal)
-    Use the Gmail API to search for email threads based on a specific query.
+4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads)
+    Search for email threads based on a specified query.
 
 ## Report Issues
 

changelog.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Improve documentation
+
 ### Changed
 
 ## [4.0.0] - 2023-12-01

examples/README.md

@@ -2,21 +2,18 @@
 
 The `gmail` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples), covering use cases like sending emails, retrieving messages, and managing labels.
 
-1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails/main.bal)
-    Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
+1. [Process customer feedback emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/process-mails) - Manage customer feedback emails by processing unread emails in the inbox, extracting details, and marking them as read.
 
-2. [Send maintenance break notifications](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails/main.bal)
-    Automatically send emails for scheduled maintenance breaks.
+2. [Send maintenance break emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/send-mails) - Send emails for scheduled maintenance breaks
 
-3. [Send automated response to emails](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails/main.bal)
-    Automate fetching unread emails from the Inbox and send personalized responses to customers.
+3. [Automated Email Responses](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/reply-mails) - Retrieve unread emails from the Inbox and subsequently send personalized responses.
 
-4. [Search for relevant email threads](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads/main.bal)
-    Use the Gmail API to search for email threads based on a specific query.
+4. [Email Thread Search](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail/tree/master/examples/search-threads)
+    Search for email threads based on a specified query.
 
 ## Prerequisites
 
-1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-gmail-api) to set up the Gmail API.
+1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-guide) to set up the Gmail API.
 
 2. For each example, create a `config.toml` file with your OAuth2 tokens, client ID, and client secret. Here's an example of how your `config.toml` file should look:
 

examples/process-mails/.github/README.md

@@ -0,0 +1 @@
+../Process customer feedback emails.md

examples/process-mails/Process customer feedback emails.md

@@ -0,0 +1,29 @@
+# Process customer feedback emails
+
+This example demonstrates how to efficiently manage customer feedback emails. The Ballerina programme retrieves unread messages from the INBOX, extracts sender and subject information, and stores it in a CSV file for later access.
+
+## Prerequisites
+
+### 1. Set up Gmail API
+
+Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens).
+
+### 2. Configuration
+
+Configure Gmail API credentials in `Config.toml` in the example directory:
+
+```toml
+refreshToken="<Refresh Token>"
+clientId="<Client Id>"
+clientSecret="<Client Secret>"
+```
+
+## Run the Example
+
+Execute the following command to run the example:
+
+```bash
+bal run
+```
+
+Check the results in the generated `feedback.csv` file.

examples/reply-mails/.github/README.md

@@ -0,0 +1 @@
+../Automated Email Responses.md

examples/reply-mails/Automated Email Responses.md

@@ -0,0 +1,27 @@
+# Automated Email Responses
+
+This example demonstrates the automated retrieval of unread emails from the Inbox and the subsequent sending of personalized responses.
+
+## Prerequisites
+
+### 1. Set up Gmail API
+
+Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens).
+
+### 2. Configuration
+
+Configure Gmail API credentials in `Config.toml` in the example directory:
+
+```toml
+refreshToken="<Refresh Token>"
+clientId="<Client Id>"
+clientSecret="<Client Secret>"
+```
+
+## Run the Example
+
+Execute the following command to run the example:
+
+```bash
+bal run
+```

examples/search-threads/.github/README.md

@@ -0,0 +1 @@
+../Email Thread Search.md

examples/search-threads/Email Thread Search.md

@@ -0,0 +1,27 @@
+# Email thread search
+
+This example showcases an efficient method to search for email threads based on a specified query. The code extracts and displays the subject and snippet of the first message in each relevant thread for streamlined information retrieval.
+
+## Prerequisites
+
+### 1. Set up Gmail API
+
+Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens).
+
+### 2. Configuration
+
+Configure Gmail API credentials in `Config.toml` in the example directory:
+
+```toml
+refreshToken="<Refresh Token>"
+clientId="<Client Id>"
+clientSecret="<Client Secret>"
+```
+
+## Run the Example
+
+Execute the following command to run the example:
+
+```bash
+bal run
+```

examples/send-mails/.github/README.md

@@ -0,0 +1 @@
+../Send Maintenance Break Emails.md

examples/send-mails/Send Maintenance Break Emails.md

@@ -0,0 +1,28 @@
+# Send maintenance break emails
+
+This example demonstrates the automated sending of emails for scheduled maintenance breaks.
+
+## Prerequisites
+
+### 1. Set up Gmail API
+
+Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens).
+
+### 2. Configuration
+
+Configure Gmail API credentials in `Config.toml` in the example directory:
+
+```toml
+refreshToken="<Refresh Token>"
+clientId="<Client Id>"
+clientSecret="<Client Secret>"
+recipient="<Recipient Email Address>"
+```
+
+## Run the Example
+
+Execute the following command to run the example:
+
+```bash
+bal run
+```