Skip to content

Commit

Permalink
Merge pull request #44 from UBC-MDS/autogen
Browse files Browse the repository at this point in the history 
feat: Address Feedback + Autogen Docstring
  • Loading branch information
@mikem2m
mikem2m authored Jan 31, 2025
2 parents 9e9893d + b3c9713 commit 8258e05
Show file tree
Hide file tree
Showing 12 changed files with 707 additions and 87 deletions.
14 changes: 13 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,12 +38,16 @@ def square(base: int, pow: int) -> int:
print(generate_docstring_template(square, output_file=None))
```

## OpenAI Dependency:

`fml_doc_gen` requires an OpenAI API key to generate docstrings. You can set your API key using the `OPENAI_API_KEY` environment variable. Check our our documentation [here](https://readthedocs.org/projects/fml-doc-gen/badge/?version=latest) for more information.

## Functions Included

- **`generate_docstring_template(func: Callable, output_file: str, auto_generate: bool = False) -> str`**:
The main end-user function that generates either a docstring template with placeholders or a fully detailed docstring if `auto_generate` is set to `True`.

- **`read_user_function(func: Callable) -> str`**:
- **`read_user_function(func: Callable) -> FunctionDTO`**:
Reads and extracts the signature and existing docstring (if any) of a given user-defined function.

- **`generate_template(func_signature: str) -> str`**:
Expand All @@ -62,6 +66,14 @@ If you are aware of a similar tool, feel free to contribute to our documentation

Found a bug? or have an idea on how to improve `fml_doc_gen` further? Feel free to open an issue with the appropriate label (bug or features) under the issue section [here](https://github.com/UBC-MDS/fml_doc_gen/issues).

## Running Tests

To run tests and check code coverage, use the following command in the project root:

```bash
poetry run pytest --cov=fml_doc_gen --cov-report=term-missing tests/
```

## Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
Expand Down
6 changes: 3 additions & 3 deletions docs/doc.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,19 @@
Parameters:
----------

base: int
base: <class 'int'>
### INSERT PARAMETER DEFINITION HERE ###


pow: int
pow: <class 'int'>
### INSERT PARAMETER DEFINITION HERE ###




Returns:
-------
int
<class 'int'>
### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ###


Expand Down
117 changes: 92 additions & 25 deletions docs/example.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
},
{
"cell_type": "code",
"execution_count": 13,
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -41,14 +41,14 @@
},
{
"cell_type": "code",
"execution_count": 17,
"execution_count": 2,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"0.0.1\n"
"3.0.4\n"
]
}
],
Expand All @@ -68,7 +68,7 @@
},
{
"cell_type": "code",
"execution_count": 18,
"execution_count": 3,
"metadata": {},
"outputs": [
{
Expand All @@ -82,19 +82,19 @@
" Parameters:\n",
" ----------\n",
" \n",
" base: int\n",
" base: <class 'int'>\n",
" ### INSERT PARAMETER DEFINITION HERE ###\n",
" \n",
"\n",
" pow: int\n",
" pow: <class 'int'>\n",
" ### INSERT PARAMETER DEFINITION HERE ###\n",
" \n",
"\n",
"\n",
" \n",
" Returns:\n",
" -------\n",
" int\n",
" <class 'int'>\n",
" ### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ###\n",
"\n",
" \n",
Expand Down Expand Up @@ -168,7 +168,7 @@
},
{
"cell_type": "code",
"execution_count": 19,
"execution_count": 4,
"metadata": {},
"outputs": [
{
Expand All @@ -182,19 +182,19 @@
" Parameters:\n",
" ----------\n",
" \n",
" base: int\n",
" base: <class 'int'>\n",
" ### INSERT PARAMETER DEFINITION HERE ###\n",
" \n",
"\n",
" pow: int\n",
" pow: <class 'int'>\n",
" ### INSERT PARAMETER DEFINITION HERE ###\n",
" \n",
"\n",
"\n",
" \n",
" Returns:\n",
" -------\n",
" int\n",
" <class 'int'>\n",
" ### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ###\n",
"\n",
" \n",
Expand Down Expand Up @@ -233,30 +233,97 @@
" Unsure about writing documentation? We’ve got you covered! \n",
" </h3> \n",
"\n",
"Simply pass the `auto_generate` parameter to our function, and we’ll create the documentation for you automatically.\n",
"Follow the steps below to setup openAI.\n",
"\n",
"Then Simply pass the `auto_generate` parameter to our function, and we’ll create the documentation for you automatically.\n",
"\n",
"<b>\n",
" Note: This feature is currently under development and will be available soon. Stay tuned!\n",
" Note: This feature is currently still under development and may have issues!\n",
"</b>\n",
"</div>\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"**Step 1: Create an OpenAI Account** \n",
"\n",
"- Sign up for an OpenAI account if you haven’t already. You can do this here: \n",
"🔗 [OpenAI Sign Up](https://platform.openai.com/signup/)\n",
"\n",
"**Step 2: Obtain Your API Key** \n",
"1. Log in to your OpenAI account. \n",
"2. Navigate to the **API Keys** section. \n",
"3. Generate a new API key. \n",
"4. Copy the key and store it securely. \n",
"\n",
"**Step 3: Store the API Key in a `.env` File** \n",
"1. In your project root directory, create a `.env` file if it doesn’t already exist. \n",
"2. Open the `.env` file and add the following line: \n",
" ```env\n",
" OPENAI_API_KEY=your-api-key-here\n",
" ```\n"
]
},
{
"cell_type": "code",
"execution_count": 12,
"execution_count": 5,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"CALL OPEN AI API HERE\n"
]
}
],
"outputs": [],
"source": [
"documentation = generate_docstring_template(square, output_file=None, auto_generate=True)\n",
"print(documentation)"
"documentation = generate_docstring_template(square, output_file=None, auto_generate=True)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```python\n",
"def square(base: int, pow: int) -> int:\n",
" \"\"\"\n",
" Square: \n",
" This function returns the base raised to an integer power.\n",
"\n",
" Parameters:\n",
" ----------\n",
"\n",
" base: <class 'int'>\n",
" The base number that would be raised to a certain power. This should be an integer.\n",
"\n",
" pow: <class 'int'>\n",
" The power to which the base number would be raised. This should be an integer.\n",
"\n",
"\n",
"\n",
"\n",
" Returns:\n",
" -------\n",
" <class 'int'>\n",
" The result is an integer that is the base raised to the specified power.\n",
"\n",
"\n",
"\n",
" Examples:\n",
" --------\n",
" Here are a few examples of function usages:\n",
"\n",
" square(2, 3)\n",
" Returns: 8\n",
" Explanation: 2 raised to the power of 3 equals 8.\n",
"\n",
" square(5, 2)\n",
" Returns: 25\n",
" Explanation: 5 raised to the power of 2 equals 25.\n",
"\n",
" square(3, 0)\n",
" Returns: 1\n",
" Explanation: Any number raised to the power of 0 equals 1.\n",
" \"\"\"\n",
" \n",
" return base ** pow\n",
"```\n",
"\n"
]
}
],
Expand Down
Loading

0 comments on commit 8258e05

Please sign in to comment.