From ddc9b049261750dd142f333cf562d016d8c27ca3 Mon Sep 17 00:00:00 2001 From: Harshad Hegde Date: Mon, 12 Feb 2024 17:02:38 -0600 Subject: [PATCH] updated docs --- README.md | 316 +++++++++++++----------------------------------------- 1 file changed, 73 insertions(+), 243 deletions(-) diff --git a/README.md b/README.md index 59c8272..ffeaa7a 100644 --- a/README.md +++ b/README.md @@ -1,300 +1,130 @@ # CoderGPT -## Description +CoderGPT is a versatile command-line interface (CLI) designed to enhance coding workflows. It leverages the capabilities of Large Language Models (LLM) and Generative Pre-trained Transformers (GPT) to assist developers in various tasks such as commenting, optimizing, documenting, and testing their code. This tool integrates seamlessly with [langchain](https://github.com/langchain-ai/langchain), providing a powerful backend for code generation and modification. -CoderGPT is a command line interface for generating/modifying code. It allows developers to enhance code by commenting, optimizing, documenting, and adding tests to their project using the power of LLM and GPT. This project is powered by [langchain](https://github.com/langchain-ai/langchain). +## Prerequisites - -**_NOTE:_** -Before using CoderGPT, ensure that the environment variable `OPENAI_API_KEY` is set locally on your machine. This key is required for authentication with the OpenAI API which powers the underlying language model. +Before you begin using CoderGPT, you must set the `OPENAI_API_KEY` environment variable on your machine. This key enables authentication with the OpenAI API, which is essential for the language model's operation. ```sh export OPENAI_API_KEY='your-api-key-here' ``` -Replace `your-api-key-here` with your actual OpenAI API key. This step is crucial for the proper functioning of CoderGPT as it relies on the OpenAI API for generating and modifying code. +Ensure that you replace `your-api-key-here` with your actual OpenAI API key to enable the full functionality of CoderGPT. +## Getting Started -## Installation +### Installation -To use the CoderGPT CLI, clone the repository and install the required dependencies. +Install CoderGPT easily using pip: ```shell pip install codergpt ``` -## Usage +### Basic Usage -Run the CLI using the following syntax: +Invoke the CoderGPT CLI with the following syntax: ```shell codergpt [OPTIONS] COMMAND [ARGS]... ``` -### Options - -- `-v, --verbose INTEGER`: Set verbosity level (0, 1, or 2). -- `-q, --quiet`: Enable quiet mode. -- `--version`: Display version information. - -### Commands - -1. `inspect`: Inspect a package and display a file-language map. - - - ```shell - codergpt inspect - ``` - - #### Example - ```shell - $ codergpt inspect src/codergpt/ - Inspecting the code. - File Language - ------------------------------------------ ---------- - src/codergpt/constants.py Python - src/codergpt/__init__.py Python - src/codergpt/cli.py Python - src/codergpt/extensions.yaml YAML - src/codergpt/main.py Python - src/codergpt/optimizer/__init__.py Python - src/codergpt/utils/expression_evaluator.py Python - src/codergpt/utils/__init__.py Python - src/codergpt/commenter/commenter.py Python - src/codergpt/commenter/__init__.py Python - src/codergpt/explainer/explainer.py Python - src/codergpt/explainer/__init__.py Python - src/codergpt/test_writer/__init__.py Python - ``` - - -2. `explain`: Explain a specific function or class within a package. - - ```shell - codergpt explain [--function ] [--classname ] - ``` - - #### Example - ```shell - $ codergpt explain src/codergpt/explainer/explainer.py --function explain - Explanation for the code: - This code defines a method called `explain` that takes in three parameters: `code`, `function`, and `classname`. The `code` parameter is a string that represents the code file to be explained. The `function` parameter is an optional string that represents the name of a specific function within the code file that needs to be explained. The `classname` parameter is also an optional string that represents the name of a specific class within the code file that needs to be explained. - - The method first checks if the `function` parameter is provided. If it is, the method invokes a `chain` by passing a dictionary with an "input" key and a formatted string containing the code. The response from the `chain.invoke` call is then printed in a pretty format, including the name of the function being explained. - - If the `function` parameter is not provided but the `classname` parameter is, the same process is followed, but with the class name instead. - - If both `function` and `classname` parameters are not provided, the method assumes that the full code needs to be explained. It again invokes the `chain` with the code as input and prints the response in a pretty format, indicating that it is explaining the entire code. - ``` - -3. `comment`: Add comments to the code in a package. The user has the choice to overwrite the file or create a new one. - - ```shell - codergpt comment [--overwrite/--no-overwrite] - ``` - #### Example - - Let's consider a python file `greetings.py`: - ```python - def greet(name): - return f"Hello, {name}!" - - if __name__ == "__main__": - user_name = "Alice" - print(greet(user_name)) - ``` - - ```shell - $ codergpt comment greetings.py --overwrite - ``` - results in .... - ```python - def greet(name): - """ - Generates a greeting message for the given name. - - :param name: (str) The name of the person to greet. - :return: (str) The greeting message. - """ - return f"Hello, {name}!" - - - if __name__ == "__main__": - user_name = "Alice" - print(greet(user_name)) - ``` -4. `optimize`: Optimizes and adds commets to the code in a package. The user has the choice to overwrite the file or create a new one. - - ```shell - codergpt optimize [--overwrite/--no-overwrite] - ``` - #### Example - - Let's consider a python file `example.py`: - ```python - # example.py - - def calculate_sum(numbers): - result = 0 - for number in numbers: - result += number - return result - - class MathOperations: - def multiply(self, a, b): - answer = 0 - for i in range(b): - answer += a - return answer - ``` - ```shell - $ codergpt optimize example.py --overwrite - ``` - results in .... - ```python - """ - Optimized and Documented Code: - - """ - - from typing import List - - - def calculate_sum(numbers: List[int]) -> int: - """ - Calculates the sum of a list of numbers. - - Parameters: - numbers (List[int]): A list of integers. - - Returns: - int: The sum of the numbers. +#### Options - """ - result = sum(numbers) - return result +- `-v, --verbose INTEGER`: Adjust the verbosity level (0 for default, 1 for verbose, 2 for debug). +- `-q, --quiet`: Suppress output. +- `--version`: Show the version number and exit. +#### Commands - class MathOperations: - def multiply(self, a: int, b: int) -> int: - """ - Multiplies two numbers. +##### Inspect - Parameters: - a (int): The first number. - b (int): The second number. +Analyze a package and display its file-language mapping. - Returns: - int: The result of multiplying a and b. - - """ - answer = a * b - return answer +```shell +codergpt inspect +``` +###### Example - """ - Optimization: +```shell +$ codergpt inspect src/codergpt/ +``` - 1. In the 'calculate_sum' function, we can use the built-in 'sum' function to calculate the sum of the numbers in the list. This is more efficient than manually iterating over the list and adding each number to the result. +##### Explain - 2. In the 'multiply' method of the 'MathOperations' class, we can directly multiply the two numbers using the '*' operator. This eliminates the need for a loop and improves performance. +Provide an explanation for a specific function or class within a package. - By using these optimizations, we improve the efficiency and readability of the code. - """ - ``` +```shell +codergpt explain [--function ] [--classname ] +``` -5. `write-tests`: Writes tests for the specified code file, with options to target specific functions and/or classes within the file. +###### Example - ```shell - codergpt write-tests [--function ] [--class ] [--outfile ] - ``` +```shell +$ codergpt explain src/codergpt/explainer/explainer.py --function explain +``` - #### Example - - Consider a Python file `example.py`: - ```python - # example.py +##### Comment - def add(a, b): - return a + b +Automatically add comments to your code. Choose whether to overwrite the existing file or create a new one. - class Calculator: - def subtract(self, a, b): - return a - b - ``` - - To generate test cases for both the `add` function and the `Calculator` class in `example.py`, run the following command: - ```shell - $ codergpt write-tests example.py --function add --class Calculator - ``` - This results in test files being generated that contain test cases for the specified `add` function and the `Calculator` class. The output file will be named `test_example.py` and saved in the directory specified by `TEST_DIR`. If an `--outfile` is provided, the tests will be written to that file instead. +```shell +codergpt comment [--overwrite/--no-overwrite] +``` - The actual content of the test files will depend on the implementation of the `CodeTester.write_tests` method but would typically include structured tests like this: +###### Example - ```python - import unittest - from example import add, Calculator +```shell +$ codergpt comment greetings.py --overwrite +``` - class TestAddFunction(unittest.TestCase): +##### Optimize - def test_addition(self): - self.assertEqual(add(3, 4), 7) +Enhance your code by optimizing it and adding comments. You can decide to overwrite the original file or save the changes separately. - class TestCalculator(unittest.TestCase): +```shell +codergpt optimize [--overwrite/--no-overwrite] +``` - def setUp(self): - self.calc = Calculator() +###### Example - def test_subtract(self): - self.assertEqual(self.calc.subtract(10, 5), 5) - ``` +```shell +$ codergpt optimize example.py --overwrite +``` - In this example, running the command generates unit tests for both the `add` function and the `Calculator` class in the `example.py` file. The tests verify that the `add` function correctly adds two numbers and that the `Calculator`'s `subtract` method correctly subtracts one number from another. +##### Write Tests -6. `document`: Generates documentation for the specified code file by invoking a runnable chain that processes and explains the code. +Generate test cases for a specified code file, targeting particular functions and/or classes. ```shell -codergpt document [--outfile ]s +codergpt write-tests [--function ] [--class ] [--outfile ] ``` -#### Example -- Consider a Python file `example.py`: -```python -# example.py - -def add(a, b): - """Add two numbers and return the result.""" - return a + b - -class Calculator: - """A simple calculator class.""" +###### Example - def subtract(self, a, b): - """Subtract b from a and return the result.""" - return a - b -``` -- To generate documentation for `example.py`, run the following command: ```shell -$ codergpt document example.py +$ codergpt write-tests example.py --function add --class Calculator ``` -This results in documentation files being generated that contain explanations for all functions and classes within the `example.py` file. The output file will be named after the input file with an `.rst` extension and saved in the directory specified by `DOCS_DIR`. If an `` is provided, the documentation will be written to that file instead. -The actual content of the documentation files will depend on the implementation of the `CodeDocumenter.document` method but would typically include structured documentation like this: +##### Document -```rst -add Function ------------- +Create documentation for a given code file by processing and explaining the code. -.. autofunction:: example.add +```shell +codergpt document [--outfile ] +``` -Calculator Class ----------------- +###### Example -.. autoclass:: example.Calculator - :members: +```shell +$ codergpt document example.py ``` -In this example, running the command generates ReStructuredText (RST) formatted documentation for the entire `example.py` file, including both the `add` function and the `Calculator` class. The documentation includes descriptions of the function and class, as well as any public methods of the class. - -## Development +## Development & Contribution -The CLI is built using Python and the `click` library. Below is an example of how to define a new command: +The CoderGPT CLI is developed in Python, utilizing the `click` library for creating commands. Here's a template for adding a new command: ```python import click @@ -305,20 +135,20 @@ coder = CoderGPT() @click.command() @click.argument('path', type=click.Path(exists=True)) def new_command(path): - # Command logic here + # Implement command logic here pass ``` -## Contributing - -Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) before submitting pull requests. +Contributions to CoderGPT are highly encouraged! Please review our [contributing guidelines](CONTRIBUTING.md) before making pull requests. ## License -This project is licensed under the MIT License - see the LICENSE.md file for details. +CoderGPT is open-sourced under the MIT License. For more details, refer to the [LICENSE.md](LICENSE.md) file. + +## Acknowledgments -## Acknowledgements +This project was scaffolded using the [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/README.html) framework, based on the [monarch-project-template](https://github.com/monarch-initiative/monarch-project-template). Updates are managed through [cruft](https://cruft.github.io/cruft/). -This [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/README.html) project was developed from the [monarch-project-template](https://github.com/monarch-initiative/monarch-project-template) template and will be kept up-to-date using [cruft](https://cruft.github.io/cruft/). +For comprehensive details on the CoderGPT CLI, please refer to [the official documentation](#). -For more information on CoderGPT CLI, please visit [the official documentation](). +--- \ No newline at end of file