{
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Exploring `fml_doc_gen`"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Let's say you have the following function you want to generate the documentation for:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 1,
            "metadata": {},
            "outputs": [],
            "source": [
                "def square(base: int, pow: int) -> int:\n",
                "    return base ** pow"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<!-- <div class=\"alert alert-info\">  -->\n",
                "<h3>\n",
                "    But you forgot what the template looks like? Don’t worry!\n",
                "</h3>\n",
                "\n",
                "This is where `fml_doc_gen` comes to the rescue.\n",
                "\n",
                "<b>To get started, simply import our package:</b>\n",
                "<!-- </div> -->"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 2,
            "metadata": {},
            "outputs": [
                {
                    "name": "stdout",
                    "output_type": "stream",
                    "text": [
                        "3.0.4\n"
                    ]
                }
            ],
            "source": [
                "import fml_doc_gen\n",
                "from fml_doc_gen.fml_doc_gen import generate_docstring_template\n",
                "\n",
                "print(fml_doc_gen.__version__)"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<b>Simply pass your function to ours to generate the documentation effortlessly:</b>"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 3,
            "metadata": {},
            "outputs": [
                {
                    "name": "stdout",
                    "output_type": "stream",
                    "text": [
                        "\n",
                        "    square: \n",
                        "    ### INSERT FUNCTION DEFINITION HERE ###\n",
                        "    \n",
                        "    Parameters:\n",
                        "    ----------\n",
                        "    \n",
                        "    base: <class 'int'>\n",
                        "    ### INSERT PARAMETER DEFINITION HERE ###\n",
                        "    \n",
                        "\n",
                        "    pow: <class 'int'>\n",
                        "    ### INSERT PARAMETER DEFINITION HERE ###\n",
                        "    \n",
                        "\n",
                        "\n",
                        "    \n",
                        "    Returns:\n",
                        "    -------\n",
                        "    <class 'int'>\n",
                        "        ### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ###\n",
                        "\n",
                        "      \n",
                        "    Examples:\n",
                        "    --------\n",
                        "    ### INSERT FUNCTION EXAMPLE USAGES HERE ###\n",
                        "\n"
                    ]
                }
            ],
            "source": [
                "documentation = generate_docstring_template(square, output_file=None)\n",
                "print(documentation)"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Then you can copy this and make your function fully documented as follows"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "```python\n",
                "def square(base: int, pow: int) -> int:\n",
                "    \"\"\"\n",
                "    square: \n",
                "    ### INSERT FUNCTION DEFINITION HERE ###\n",
                "    \n",
                "    Parameters:\n",
                "    ----------\n",
                "    \n",
                "    base: int\n",
                "    ### INSERT PARAMETER DEFINITION HERE ###\n",
                "    \n",
                "\n",
                "    pow: int\n",
                "    ### INSERT PARAMETER DEFINITION HERE ###\n",
                "    \n",
                "    \n",
                "    Returns:\n",
                "    -------\n",
                "    int\n",
                "        ### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ###\n",
                "\n",
                "      \n",
                "    Examples:\n",
                "    --------\n",
                "    ### INSERT FUNCTION EXAMPLE USAGES HERE ###\n",
                "\n",
                "    \"\"\"\n",
                "    \n",
                "    return base ** pow\n",
                "\n",
                "```"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<h3>This is just what you needed, right?</h3>\n",
                "\n",
                "But wait—there’s more! You can even save the generated documentation to a file.\n",
                "\n",
                "Simply pass a file path to the previous function:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 4,
            "metadata": {},
            "outputs": [
                {
                    "name": "stdout",
                    "output_type": "stream",
                    "text": [
                        "\n",
                        "    square: \n",
                        "    ### INSERT FUNCTION DEFINITION HERE ###\n",
                        "    \n",
                        "    Parameters:\n",
                        "    ----------\n",
                        "    \n",
                        "    base: <class 'int'>\n",
                        "    ### INSERT PARAMETER DEFINITION HERE ###\n",
                        "    \n",
                        "\n",
                        "    pow: <class 'int'>\n",
                        "    ### INSERT PARAMETER DEFINITION HERE ###\n",
                        "    \n",
                        "\n",
                        "\n",
                        "    \n",
                        "    Returns:\n",
                        "    -------\n",
                        "    <class 'int'>\n",
                        "        ### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ###\n",
                        "\n",
                        "      \n",
                        "    Examples:\n",
                        "    --------\n",
                        "    ### INSERT FUNCTION EXAMPLE USAGES HERE ###\n",
                        "\n"
                    ]
                }
            ],
            "source": [
                "documentation = generate_docstring_template(square, output_file=\"./doc.txt\")\n",
                "print(documentation)"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<b> Even if you don't have the output file, we will create it for you. </b>"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "![Documentation Example](doc_img.png)"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<div class=\"alert alert-warning\">\n",
                "    <h3> \n",
                "        Unsure about writing documentation? We’ve got you covered! \n",
                "    </h3> \n",
                "\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 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": "markdown",
            "metadata": {},
            "source": [
                "```\n",
                "documentation = generate_docstring_template(square, output_file=None, auto_generate=True)\n",
                "```"
            ]
        },
        {
            "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"
            ]
        }
    ],
    "metadata": {
        "kernelspec": {
            "display_name": "fml",
            "language": "python",
            "name": "python3"
        },
        "language_info": {
            "codemirror_mode": {
                "name": "ipython",
                "version": 3
            },
            "file_extension": ".py",
            "mimetype": "text/x-python",
            "name": "python",
            "nbconvert_exporter": "python",
            "pygments_lexer": "ipython3",
            "version": "3.10.16"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 4
}