Merge pull request #5 from hrshdhgd/documenter

Add `documenter` feature

README.md

@@ -2,9 +2,19 @@
 
 ## Description
 
-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).
+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).
+
+---
+**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.
+
+```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.
+
+---
 
 ## Installation
 
@@ -194,47 +204,88 @@ code [OPTIONS] COMMAND [ARGS]...
 
 5. `write-tests`: Writes tests for the specified code file. The user can specify a function and/or a class within the file to target with the tests.
 
-```shell
-code write-tests <path> [--function <function_name>] [--class <classname>]
-```
+    ```shell
+    code write-tests <path> [--function <function_name>] [--class <classname>]
+    ```
 
-#### Example
-- Let's consider a python file `example.py`:
-```python
-# example.py
+    #### Example
+    - Let's consider a python file `example.py`:
+    ```python
+    # example.py
 
-def add(a, b):
-    return a + b
+    def add(a, b):
+        return a + b
 
-class Calculator:
-    def subtract(self, a, b):
-        return a - b
-```
-```shell
-$ code write-tests example.py --function add --class Calculator
-```
-results in test files being generated that contain test cases for the `add` function and the `Calculator` class. The actual content of the test files will depend on the implementation of the `coder.test_writer` method but would typically look something like this:
+    class Calculator:
+        def subtract(self, a, b):
+            return a - b
+    ```
+    ```shell
+    $ code write-tests example.py --function add --class Calculator
+    ```
+    results in test files being generated that contain test cases for the `add` function and the `Calculator` class. The actual content of the test files will depend on the implementation of the `coder.test_writer` method but would typically look something like this:
 
-```python
-import unittest
-from example import add, Calculator
+    ```python
+    import unittest
+    from example import add, Calculator
 
-class TestAddFunction(unittest.TestCase):
+    class TestAddFunction(unittest.TestCase):
 
-    def test_addition(self):
-        self.assertEqual(add(3, 4), 7)
+        def test_addition(self):
+            self.assertEqual(add(3, 4), 7)
 
-class TestCalculator(unittest.TestCase):
+    class TestCalculator(unittest.TestCase):
 
-    def setUp(self):
-        self.calc = Calculator()
+        def setUp(self):
+            self.calc = Calculator()
 
-    def test_subtract(self):
-        self.assertEqual(self.calc.subtract(10, 5), 5)
-```
+        def test_subtract(self):
+            self.assertEqual(self.calc.subtract(10, 5), 5)
+    ```
+
+    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 check if the `add` function correctly adds two numbers and if the `Calculator`'s `subtract` method correctly subtracts one number from another.
+
+6. `document`: Generates documentation for the specified code file.
+
+    ```shell
+    code document <path>
+    ```
+
+    #### Example
+    - Let's 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."""
 
-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 check if the `add` function correctly adds two numbers and if the `Calculator`'s `subtract` method correctly subtracts one number from another.
+        def subtract(self, a, b):
+            """Subtract b from a and return the result."""
+            return a - b
+    ```
+    ```shell
+    $ code document example.py
+    ```
+    results in documentation files being generated that contain documentation for all functions and classes within the `example.py` file. The actual content of the documentation files will depend on the implementation of the `DocumentationGenerator.document` method but would typically look something like this:
+
+    ```rst
+    add Function
+    ------------
+
+    .. autofunction:: example.add
+
+    Calculator Class
+    ----------------
+
+    .. autoclass:: example.Calculator
+    :members:
+    ```
 
+    In this example, running the command generates 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
 

docs/cli.rst

@@ -0,0 +1,104 @@
+Command line interface for CoderGPT
+====================================
+
+This module provides a command line interface (CLI) for CoderGPT, a powerful code generation tool designed to assist in various coding tasks, including inspection, explanation, commenting, optimization, test writing, and documentation of code files.
+
+.. moduleauthor:: Harshad Hegde
+
+Usage
+-----
+
+To use this CLI, run the following command in your terminal:
+
+.. code-block:: shell
+
+    python codergpt_cli.py [OPTIONS] COMMAND [ARGS]...
+
+Options
+-------
+
+-v, --verbose INTEGER
+  Verbosity level, which can be set to 0, 1, or 2.
+
+-q, --quiet
+  Activate quiet mode, limiting output messages.
+
+--version
+  Display the current version of CoderGPT and exit.
+
+Commands
+--------
+
+**inspect**
+  Inspect a package to show a file-language map. Requires a path to the package as an argument.
+
+**explain**
+  Provide explanations for a specified function or class within a file. This command requires a path and can optionally include a function name and a class name.
+
+**comment**
+  Add comments to a code file. This command requires a path to the file and accepts an overwrite flag to indicate whether existing files should be overwritten.
+
+**optimize**
+  Optimize a code file by improving its performance or code quality. This command requires a path to the file and can optionally include a function name, a class name, and an overwrite flag.
+
+**write-tests**
+  Generate test cases for a specified function or class within a file. This command requires a path and can optionally include a function name and a class name.
+
+**document**
+  Write documentation files for a code file. This command requires a path to the file.
+
+.. note:: All path arguments can be a string path, a :class:`pathlib.Path` object, or a file object.
+
+Examples
+--------
+
+Inspect a package:
+
+.. code-block:: shell
+
+    python codergpt_cli.py inspect /path/to/package
+
+Explain a function in a file:
+
+.. code-block:: shell
+
+    python codergpt_cli.py explain -f my_function /path/to/file.py
+
+Add comments to a file with overwrite enabled:
+
+.. code-block:: shell
+
+    python codergpt_cli.py comment --overwrite /path/to/file.py
+
+Optimize a class within a file without overwriting:
+
+.. code-block:: shell
+
+    python codergpt_cli.py optimize -c MyClass /path/to/file.py
+
+Write tests for a function:
+
+.. code-block:: shell
+
+    python codergpt_cli.py write-tests -f my_function /path/to/file.py
+
+Write documentation for a file:
+
+.. code-block:: shell
+
+    python codergpt_cli.py document /path/to/file.py
+
+Parameters and Options
+----------------------
+
+-path
+  The path to the code file, package, or directory. This is a required argument for all commands.
+
+-f, --function
+  The name of the function to explain, optimize, or write tests for. This is an optional argument for the ``explain``, ``optimize``, and ``write-tests`` commands.
+
+-c, --classname
+  The name of the class to explain, optimize, or write tests for. This is an optional argument for the ``explain``, ``optimize``, and ``write-tests`` commands.
+
+--overwrite/--no-overwrite
+  A flag indicating whether to overwrite the existing file. This is an optional argument for the ``comment`` and ``optimize`` commands.

docs/commenter.rst

@@ -0,0 +1,57 @@
+Commenter Module
+================
+
+This module contains the CodeCommenter class, which is designed to enhance code readability by automatically adding comments and Sphinx-compatible docstrings to a given piece of code.
+
+Classes
+-------
+
+CodeCommenter
+^^^^^^^^^^^^^
+
+.. autoclass:: CodeCommenter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   The CodeCommenter class leverages a runnable chain to analyze code and generate explanatory comments and docstrings.
+
+   .. automethod:: __init__
+   .. automethod:: comment
+
+Methods
+-------
+
+__init__(self, chain)
+~~~~~~~~~~~~~~~~~~~~~
+
+Initializes the CodeCommenter class with a specified runnable chain.
+
+:parameter chain: A ``RunnableSerializable`` object that is capable of executing defined tasks. This chain is responsible for the primary operation of analyzing and generating comments for the provided code.
+:type chain: RunnableSerializable[Dict, Any]
+
+comment(self, code, filename, overwrite=False, language=None)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generates comments for the given code and writes the commented code to a file.
+
+:parameter code: The code for which comments are to be generated. This should be a string containing the source code.
+:type code: str
+
+:parameter filename: The name of the original file from which the code was extracted. This filename is used to generate a new filename for the commented code unless ``overwrite`` is set to True.
+:type filename: str
+
+:parameter overwrite: Determines whether the original file should be overwritten with the commented code. By default, this is set to False, and the commented code is written to a new file with an "_updated" suffix.
+:type overwrite: bool, optional
+
+:parameter language: The programming language of the code. This is an optional parameter that can be used to specify the language if it cannot be inferred from the code or filename. Providing this information can help the runnable chain to generate more accurate and language-appropriate comments.
+:type language: Optional[str], optional
+
+This method first invokes the runnable chain with the provided code and an instruction to add comments and Sphinx-compatible docstrings in a specific format. The response from the chain is expected to contain the commented code, which is then written to either a new file or the original file based on the ``overwrite`` parameter.
+
+Dependencies
+------------
+
+- os: Used for file path manipulation and generating new filenames.
+- typing: Provides support for type hints.
+