Improve docs as per guidline

README.md

@@ -1,52 +1,182 @@
 # Ballerina GitHub Connector
-===================
 
-[![Build](https://github.com/ballerina-platform/module-ballerinax-github/workflows/CI/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-github/actions?query=workflow%3ACI)
+[![Build](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/ci.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/ci.yml)
+[![Trivy](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/trivy-scan.yml)
 [![codecov](https://codecov.io/gh/ballerina-platform/module-ballerinax-github/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerinax-github)
+[![GraalVM Check](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/build-with-bal-test-graalvm.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/build-with-bal-test-graalvm.yml)
 [![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerinax-github.svg)](https://github.com/ballerina-platform/module-ballerinax-github/commits/master)
-[![GraalVM Check](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/build-with-bal-test-native.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-github/actions/workflows/build-with-bal-test-native.yml)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![GitHub Issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-library/module/github.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-library/labels/module%2Fgithub)
 
-[GitHub](https://github.com/) brings together the world's largest community of developers to discover, share, and build better software. From open source projects to private team repositories, GitHub is an all-in-one platform for collaborative development.
+[GitHub](https://github.com/) is a widely used platform for version control and collaboration, allowing developers to work together on projects from anywhere. It hosts a vast array of both open-source and private projects, providing a suite of development tools for collaborative software development.
 
-The `github` is a [Ballerina](https://ballerina.io/) connector for GitHub.
+This Ballerina connector is designed to interface with [GitHub's REST API (version 2022-11-28)](https://docs.github.com/en/rest?apiVersion=2022-11-28), facilitating programmatic access to GitHub's services. It enables developers to automate tasks, manage repositories, issues, pull requests, and more, directly from Ballerina applications.
 
-This connector provides operations for connecting and interacting with GitHub GraphQL API endpoints over the network. 
+## Set up guide
 
-For more information, go to the module(s).
--  [github](github/Module.md)
+To use the GitHub Connector in Ballerina, you must have a GitHub account and a Personal Access Token (PAT) for authentication. If you already have a GitHub account, you can integrate the connector with your existing account. If not, you can create a new GitHub account by visiting [GitHub's Sign Up page](https://github.com/) and following the registration process. Once you have a GitHub account, you can proceed to create a PAT.
 
+### Step 1: Access GitHub Settings
 
-# Building from the Source
-## Setting Up the Prerequisites
+1. Once logged in, click on the profile picture in the top-right corner of the page.
+2. Select **Settings** from the dropdown menu.
 
-1. Download and install Java SE Development Kit (JDK) version 11. You can install either [OpenJDK](https://adoptopenjdk.net/) or [Oracle](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html).
+### Step 2: Navigate to Developer Settings
 
-        > **Note:** Set the JAVA_HOME environment variable to the path name of the directory in which you installed JDK.
+1. Scroll down in the sidebar on the left side of the settings page.
+2. click on **Developer settings** located near the bottom.
 
-2. Download and install [Ballerina Swan Lake](https://ballerina.io/). 
+### Step 3: Go to Personal Access Tokens
 
-## Building the Source
-Execute the commands below to build from the source after installing Ballerina Swan Lake:
+1. Inside Developer Settings find and click on **Personal access tokens**.
 
-* To build the package:
-    ```    
-    bal build ./github
-    ```
-* To run the tests:
-    ```
-    bal test ./ballerina
+    <img src=https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-github/master/docs/setup/resources/1-developer-settings.png alt="GitHub Developer Settings" width="50%">
+
+### Step 4: Generate a New Token
+
+1. Click on the **Generate new token** button (you might be asked to enter you password again for security purposes).
+
+### Step 5: Configure & Generate the Token
+
+ - **Note**: Give your token a descriptive name so you can remember it's purpose
+ - **Expiration**: Select the duration before the token expires (e.g., 30 days, 60 days, 90 days, custom, or no expiration).
+ - **Select Scopes**: Scopes control access for the token. Choose what you need the token for (e.g., repo access, user data access). For typical repository operations, selecting `repo` is often sufficient.
+
+    <img src=https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-github/master/docs/setup/resources/2-generate-token.png alt="Generate new PAT" width="50%">
+
+## Quickstart
+
+To use the `GitHub` connector in your Ballerina application, modify the `.bal` file as follows:
+
+### Step 1: Import the connector
+
+Import the `ballerinax/github` package into your Ballerina project.
+
+```ballerina
+import ballerinax/github;
+```
+
+### Step 2: Instantiate a new connector
+
+Create a `github:ConnectionConfig` with the obtained PAT and initialize the connector with it.
+
+```ballerina
+github:ConnectionConfig gitHubConfig = {
+    auth: {
+        token: authToken
+    }
+};
+github:Client github = check new (gitHubConfig);
+```
+
+### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+#### Get Private Repositories of Authenticated User
+
+```ballerina
+github:Repository[] userRepos = check github->/user/repos(visibility = "private", 'type = ());
+```
+
+#### Create a Private Repository
+
+```ballerina
+github:User_repos_body body = {
+    name: "New Test Repo Name",
+    'private: true,
+    description: "New Test Repo Description"
+};
+github:Repository createdRepo = check github->/user/repos.post(body);
+```
+
+## Issues and projects
+
+The **Issues** and **Projects** tabs are disabled for this repository as this is part of the Ballerina library. To report bugs, request new features, start new discussions, view project boards, etc., visit the Ballerina library [parent repository](https://github.com/ballerina-platform/ballerina-library).
+
+This repository only contains the source code for the package.
+
+## Build from the source
+
+### Prerequisites
+
+1. Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:
+
+   * [Oracle JDK](https://www.oracle.com/java/technologies/downloads/)
+   * [OpenJDK](https://adoptium.net/)
+
+    > **Note:** After installation, remember to set the `JAVA_HOME` environment variable to the directory where JDK was installed.
+
+2. Download and install [Ballerina Swan Lake](https://ballerina.io/).
+
+3. Download and install [Docker](https://www.docker.com/get-started).
+
+    > **Note**: Ensure that the Docker daemon is running before executing any tests.
+
+### Build options
+
+Execute the commands below to build from the source.
+
+1. To build the package:
+
+   ```bash
+   ./gradlew clean build
+   ```
+
+2. To run the tests:
+
+   ```bash
+   ./gradlew clean test
+   ```
+
+3. To build the without the tests:
+
+   ```bash
+   ./gradlew clean build -x test
+   ```
+
+4. To run tests against different environment:
+
+   ```bash
+   ./gradlew clean test -Pgroups=<Comma separated groups/test cases>
+   ```
+
+5. To debug package with a remote debugger:
+
+   ```bash
+   ./gradlew clean build -Pdebug=<port>
+   ```
+
+6. To debug with the Ballerina language:
+
+   ```bash
+   ./gradlew clean build -PbalJavaDebug=<port>
+   ```
+
+7. Publish the generated artifacts to the local Ballerina Central repository:
+
+    ```bash
+    ./gradlew clean build -PpublishToLocalCentral=true
     ```
 
-# Contributing to Ballerina
-As an open source project, Ballerina welcomes contributions from the community. 
+8. Publish the generated artifacts to the Ballerina Central repository:
+
+   ```bash
+   ./gradlew clean build -PpublishToCentral=true
+   ```
+
+## Contribute to Ballerina
+
+As an open-source project, Ballerina welcomes contributions from the community.
+
+For more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).
+
+## Code of conduct
 
-For more information, see the [Contribution Guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/main/CONTRIBUTING.md).
+All the contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).
 
-# Code of Conduct
-All contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).
+## Useful links
 
-# Useful Links
-* Discuss code changes of the Ballerina project via [email](mailto:ballerina-dev@googlegroups.com).
+* For more information go to the [`github` package](https://lib.ballerina.io/ballerinax/github/latest).
+* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/).
 * Chat live with us via our [Discord server](https://discord.gg/ballerinalang).
 * Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.

ballerina/Module.md

@@ -1,43 +1,83 @@
-
 ## Overview
-This GitHub connector client module provides the capability to perform operations on major resource types such as `Repositories`, `Issues`, `Pull Requests`, `Projects` etc.
 
-This module supports [GitHub API](https://docs.github.com/en/graphql) v4 version and only allows to perform functions on behalf of the user who is currently logged in.
+[GitHub](https://github.com/) is a widely used platform for version control and collaboration, allowing developers to work together on projects from anywhere. It hosts a vast array of both open-source and private projects, providing a suite of development tools for collaborative software development.
+
+This Ballerina connector is designed to interface with [GitHub's REST API (version 2022-11-28)](https://docs.github.com/en/rest?apiVersion=2022-11-28), facilitating programmatic access to GitHub's services. It enables developers to automate tasks, manage repositories, issues, pull requests, and more, directly from Ballerina applications.
+
+## Set up guide
+
+To use the GitHub Connector in Ballerina, you must have a GitHub account and a Personal Access Token (PAT) for authentication. If you already have a GitHub account, you can integrate the connector with your existing account. If not, you can create a new GitHub account by visiting [GitHub's Sign Up page](https://github.com/) and following the registration process. Once you have a GitHub account, you can proceed to create a PAT.
+
+### Step 1: Access GitHub Settings
+
+1. Once logged in, click on the profile picture in the top-right corner of the page.
+2. Select **Settings** from the dropdown menu.
+
+### Step 2: Navigate to Developer Settings
 
-## Prerequisites
-Before using this connector in your Ballerina application, complete the following:
+1. Scroll down in the sidebar on the left side of the settings page.
+2. click on **Developer settings** located near the bottom.
 
-* Create account in GitHub
-* Obtain token -
-To obtain a personal access token via which the connector can access the API, follow these [steps](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+### Step 3: Go to Personal Access Tokens
 
-* Configure the connector with the obtained token
+1. Inside Developer Settings find and click on **Personal access tokens**.
+
+    <img src=https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-github/master/docs/setup/resources/1-developer-settings.png alt="GitHub Developer Settings">
+
+### Step 4: Generate a New Token
+
+1. Click on the **Generate new token** button (you might be asked to enter you password again for security purposes).
+
+### Step 5: Configure & Generate the Token
+
+ - **Note**: Give your token a descriptive name so you can remember it's purpose
+ - **Expiration**: Select the duration before the token expires (e.g., 30 days, 60 days, 90 days, custom, or no expiration).
+ - **Select Scopes**: Scopes control access for the token. Choose what you need the token for (e.g., repo access, user data access). For typical repository operations, selecting `repo` is often sufficient.
+
+    <img src=https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-github/master/docs/setup/resources/2-generate-token.png alt="Generate new PAT">
 
 ## Quickstart
-To use the GitHub connector in your Ballerina application, update the `.bal` file as follows:
 
-### Step 1: Import connector
-First, import the `ballerinax/github` module into the Ballerina project as follows.
+To use the `GitHub` connector in your Ballerina application, modify the `.bal` file as follows:
+
+### Step 1: Import the connector
+
+Import the `ballerinax/github` package into your Ballerina project.
+
 ```ballerina
 import ballerinax/github;
 ```
-### Step 2: Create a new connector instance
-Create a `github:ConnectionConfig` using your GitHub personal access token and and initialize the connector with it.
-```ballerina
 
-github:ConnectionConfig config = {
+### Step 2: Instantiate a new connector
+
+Create a `github:ConnectionConfig` with the obtained PAT and initialize the connector with it.
+
+```ballerina
+github:ConnectionConfig gitHubConfig = {
     auth: {
-        token: "authToken"
+        token: authToken
     }
 };
+github:Client github = check new (gitHubConfig);
+```
 
-github:Client githubClient = new (config);
+### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+#### Get Private Repositories of Authenticated User
 
-```
-### Step 3: Invoke connector operation
-- Get all open pull requests in a repository
 ```ballerina
-    stream<github:PullRequest,github:Error?> response = check githubClient->getPullRequests(<GitHub_Username>, <GitHub_Repository_Name>, github:PULL_REQUEST_OPEN);
+github:Repository[] userRepos = check github->/user/repos(visibility = "private", 'type = ());
 ```
-- Use `bal run` command to compile and run the Ballerina program.    
 
+#### Create a Private Repository
+
+```ballerina
+github:User_repos_body body = {
+    name: "New Test Repo Name",
+    'private: true,
+    description: "New Test Repo Description"
+};
+github:Repository createdRepo = check github->/user/repos.post(body);
+```