Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edits to README.RST #67

Merged
merged 4 commits into from
Aug 4, 2023
Merged

Edits to README.RST #67

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
af537f4
Edits to README.RST
PipKat Aug 3, 2023
8075882
Apply suggestions from code review
RobPasMue Aug 4, 2023
d766a07
fix: link
RobPasMue Aug 4, 2023
4ae2444
Merge branch 'main' into doc/review_readme
RobPasMue Aug 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 76 additions & 45 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
GitHub Reviewer bot
===================
Review Bot
==========

|pyansys| |GH-CI| |MIT| |black|

Expand All @@ -22,37 +22,37 @@ GitHub Reviewer bot
Overview
--------

``review-bot`` is a Python library that allows users to automatically generate
suggestions and improvements for patches in GitHub pull requests by leveraging
the power of OpenAI. The library generates suggestions for patch improvements,
considering different aspects such as code style, logical errors, and other
possible issues. This makes the code review process smoother and more
efficient, ensuring that your codebase remains high-quality, maintainable, and
The ``review-bot`` package is a Python development tool for leveraging
the power of OpenAI to automatically generate suggestions for improving
GitHub pull requests. To generate suggestions for improvements, this tool
considers code style, logical errors, and other possible issues. Using
this tool makes the code review process smoother and more efficient,
ensuring that your code base is high quality, easy to maintain, and
adheres to best practices.

Install with:
Install the ``review-bot`` package with this command:
RobPasMue marked this conversation as resolved.
Show resolved Hide resolved

.. code:: bash

pip install review-bot


Installation - Details
----------------------
Installation
------------

At two installation modes are provided: user and developer.
Two installation modes are provided: user and developer.

For users
^^^^^^^^^

In order to install ``review-bot``, make sure you
have the latest version of `pip`_. To do so, run:
First, to make sure that you have the latest version of `pip`_,
run this command:

.. code:: bash

python -m pip install -U pip

Then, you can simply execute:
Then, to install the ``review-bot`` package, run this command:

.. code:: bash

Expand All @@ -62,72 +62,103 @@ Then, you can simply execute:
Token configuration
-------------------

In order to use the AI project, you will need two tokens: a GitHub access token and an Azure OpenAI token. These tokens are essential for accessing the bot functionalities.
Here are the links to the respective webpages for obtaining the required tokens:
To use this tool to review GitHub pull requests, you must have two tokens for
accessing the bot functionalities:

- `GitHub Access Token <https://github.com/settings/tokens>`_
- `Azure OpenAI Token <https://portal.azure.com/>`_
- GitHub access token
- Azure OpenAI token

Please ensure that you keep your tokens confidential and avoid sharing them publicly. Additionally, always follow the best security practices to protect your project and data from unauthorized access.
Subsequent sections explain how to obtain these tokens and set them up for your project.

Ensure that you keep your tokens confidential and do not share them publicly. Additionally,
always follow the best security practices to protect your project and data from unauthorized
access.

Below, we outline the steps to obtain each token and how to set them up for your project.

GitHub access token
^^^^^^^^^^^^^^^^^^^

A GitHub access token is required to access the GitHub API for certain features, such as querying repositories, creating issues, and managing pull requests. Follow the steps below to obtain a GitHub access token:
A GitHub access token is required to access the GitHub API for certain features, such as
querying repositories, creating issues, and managing pull requests.

1. **Create a GitHub account:** if you do not have one already, sign up for a GitHub account at https://github.com/signup.
To obtain a GitHub access token, perform these steps:

2. **Generate a PAT (Personal Access Token):** once you have a GitHub account, navigate to your account settings by clicking on your profile picture in the top-right corner of the GitHub homepage and selecting "Settings" from the dropdown menu. In the settings page, navigate to "Developer settings" > "Personal access tokens."
1. **Create a GitHub account:** If you do not already have a GitHub account, sign up for one
at https://github.com/signup.

3. **Generate a new token:** click on the "Generate new token" button and follow the prompts to configure your token. You can choose the scope of access required based on your project's needs.
2. **Generate a PAT (personal access token):** After signing into your GitHub account, go to
`Personal access tokens (classic) <https://github.com/settings/tokens>`_ in your GitHub
developer settings and click the **Generate a personal access token** link. Follow
the prompts to configure your new token, choosing the scope of access required based on
your project's needs.

4. **Copy the token:** after creating the token, GitHub will display it only once. Make sure to copy the token to a safe place, as you will not be able to see it again.
4. **Copy the token:** After creating the token, GitHub displays it only once. Make sure
that you copy the token to a secure location because you are not able to see it again.

5. **Configure the token:** to use the project with your GitHub access token, you should set it as an environment variable with the following name: `GITHUB_TOKEN`.
5. **Set the token as an environment variable:** To use the project with your GitHub access
token, set the token as an environment variable having this name: ``GITHUB_TOKEN``.

Azure OpenAI token
^^^^^^^^^^^^^^^^^^

The Azure OpenAI token is necessary to access the OpenAI API for utilizing advanced AI capabilities provided by the platform. Follow the steps below to obtain an Azure OpenAI token:
The Azure OpenAI token is required to access the OpenAI API for utilizing the advanced AI
capabilities provided by `Microsoft Azure <https://portal.azure.com/>`_.

To obtain an Azure OpenAI token, perform these steps:

1. **Sign up for Azure:** If you do not already have an Azure account, sign up for a free
account at https://azure.com/free.

1. **Sign up for Azure:** if you do not have an Azure account, sign up for a free account at https://azure.com/free.
2. **Create an OpenAI resource:** Once you have an Azure account, create an OpenAI resource
in the Azure portal. This resource provides you with the necessary credentials to access
the OpenAI API.

2. **Create an OpenAI resource:** once you have an Azure account, create an OpenAI resource in the Azure portal. This will provide you with the necessary credentials to access the OpenAI API.
3. **Copy the token:** After creating the resource, Azure sends you a token (key) that
grants you access to the OpenAI services. Make sure that you copy this token to a
secure location.

3. **Obtain the token:** after creating the resource, you will receive an API key or token. Make sure to copy and keep it secure, as it will grant you access to the OpenAI services.
4. **Set the token as an environment variable:** To use the project with your Azure OpenAI
token, set the token as an environment variable having this name: ``OPEN_AI_TOKEN``.

4. **Configure the token:** to use the project with your Azure OpenAI token, you should set it as an environment variable with the following name: `OPEN_AI_TOKEN`.

Additional required environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Apart from the GitHub access token and Azure OpenAI token, there are some additional environment variables that you need to set up to customize the behavior of the AI project. These variables allow you to fine-tune various aspects of the AI model and the OpenAI API integration. Below are the environment variables that need to be configured:
In addition to setting up environment variables for the GitHub access token and Azure OpenAI
token, you must set up some additional environment variables to customize the behavior of the
OpenAI project. The following variables allow you to fine tune various aspects of the OpenAI
model and the OpenAI API integration.

**OPENAI_API_BASE**

* Description: specifies the base URL of the OpenAI Azure API. It allows you to set the API endpoint for making requests to the OpenAI services.
* Description: Specifies the base URL of the OpenAI Azure API. This environment variable
allows you to set the API endpoint for making requests to the OpenAI services.
* Example: `https://your-api-name.openai.azure.com`

**OPENAI_API_TYPE**

* Description: defines the type of the OpenAI API. It is used to specify that you are using the Azure version of OpenAI.
* Description: Defines the type of the OpenAI API. This environment variable is used to
specify that you are using the Azure version of OpenAI.
* Example: `azure`

**OPENAI_API_VERSION**

* Description: indicates the version of the OpenAI API to be used. It ensures compatibility with the specific version of the AI model.
* Description: Indicates the version of the OpenAI API to use. This environment variable
ensures compatibility with the specific version of the AI model.
* Example: `2023-05-15`

**OPENAI_MODEL**

* Description: allows users to select a particular AI model or engine provided by your Azure OpenAI deployment. You can check your deployment to see the names of your models. Different models may have varying capabilities and performance.
* Description: Allows you to select a particular AI model or engine provided by your
Azure OpenAI deployment. You can check your deployment to see the names of your models.
Different models may have varying capabilities and performance.
* Example: `gpt-3.5-turbo-france` or `text-davinci-002`

With all of the environment variables properly configured, you are all set to leverage the full potential of the review bot.
With all these environment variables properly configured, you are ready to leverage the full
potential of the review bot.

Optionally, if you are using the bot through CLI in local, you can set the Azure OpenAI variables in a JSON configuration file as in the following example.
Optionally, if you are using the review bot through CLI locally, you can set the Azure OpenAI
variables in a JSON configuration file as per this example:

.. code-block:: json

Expand All @@ -139,21 +170,21 @@ Optionally, if you are using the bot through CLI in local, you can set the Azure
"OPENAI_API_TYPE": "azure"
}

Usage
-----
CLI usage
---------

To use the CLI of the tool:
To use the CLI (command-line interface) of the review bot, run this command:

.. code:: bash

reviewbot <-r path-to-repo> [-c path-to-openai-config]


A note on pre-commit
--------------------
``pre-commit``
--------------

The style checks take advantage of `pre-commit`_. Developers are encouraged to
install this tool via:
install this tool by running this command:

.. code:: bash

Expand Down