GithubHelp home page GithubHelp logo

airtai / docstring-gen Goto Github PK

View Code? Open in Web Editor NEW
12.0 3.0 2.0 1.48 MB

Generator for docstrings

Home Page: https://docstring-gen.airt.ai

License: Apache License 2.0

Python 19.21% Jupyter Notebook 78.94% JavaScript 0.16% HTML 0.85% CSS 0.84%

docstring-gen's Introduction

docstring-gen

Instantly improve the documentation of your Python code with Codex.


PyPI PyPI - Downloads PyPI - Python Version

GitHub Workflow Status CodeQL Dependency Review

GitHub


docstring-gen is an easy-to-use Python library that uses OpenAI’s Codex model to automatically generate Google-style docstrings for Python codebase. The library is capable of reading both Jupyter notebooks and Python files, and seamlessly adds meaningful docstrings to classes and functions that lack documentation. By using docstring-gen, developers can automatically generate docstrings for their codebase, resulting in time savings and improved documentation quality.

Install

docstring-gen can be installed by running the command below. This package requires Python 3.7 or higher to work.

pip install docstring-gen

If the installation was successful, you should now have docstring-gen installed on your system. To see a full list of settings, run docstring_gen --help

If you’re excited to try the latest version, you can install it directly from GitHub by using the command: pip install git+https://github.com/airtai/docstring-gen

How to use

The docstring-gen library uses OpenAI’s Codex model to generate docstrings for your Python classes and functions. In order to use the library, you’ll need to create an API key for OpenAI.

Once you have your API key, store it in the OPENAI_API_KEY environment variable. This is a necessary step for the library to work.

To get started right away with sensible defaults, run:

docstring_gen {source_file_or_directory}

This will automatically add meaningful, Google-style docstrings to the Python classes and functions in the {source_file_or_directory} that do not already have one.

For example, a function like below without the docstring:

def concatenate_strings(s1: str, s2: str) -> str:
    if not isinstance(s1, str) or not isinstance(s2, str):
        raise TypeError("Both arguments should be strings.")
    return s1 + s2

will become similar to:

def concatenate_strings(s1: str, s2: str) -> str:
    """Concatenate two strings.

    Args:
        s1: First string
        s2: Second string

    Returns:
        The concatenated string

    Raises:
        TypeError: If s1 or s2 is not a string

    !!! note

        The above docstring is autogenerated by docstring-gen library (https://docstring-gen.airt.ai)
    """
    if not isinstance(s1, str) or not isinstance(s2, str):
        raise TypeError("Both arguments should be strings.")
    return s1 + s2

If you wish to regenerate the docstrings, you can re-run the command with the -f flag, which will remove the previous auto-generated docstrings and replace them with new ones.

docstring_gen {source_file_or_directory} -f

Note: The default behavior of the library is to add docstrings only to functions and classes that are missing them. So, if you do not provide the -f flag when re-running the command, the library will not replace previously auto-generated docstrings, assuming that the functions already have them.

If you prefer not to include the text “autogenerated by docstring-gen library” in the generated docstrings, you can use the --no-include-auto-gen-txt flag when running the command.

docstring_gen {source_file_or_directory} -f --no-include-auto-gen-txt

Now the docstring for the above function will look similar to:

def concatenate_strings(s1: str, s2: str) -> str:
    """Concatenate two strings.

    Args:
        s1: First string
        s2: Second string

    Returns:
        The concatenated string

    Raises:
        TypeError: If s1 or s2 is not a string
    """
    if not isinstance(s1, str) or not isinstance(s2, str):
        raise TypeError("Both arguments should be strings.")
    return s1 + s2

Important: The library uses the text “autogenerated by docstring-gen library” to identify which docstrings were generated by the library. When the --no-include-auto-gen-txt flag is used, this text will not be included in the generated docstrings. As a result, when re-running the command with the -f flag, these docstrings will not be replaced.”

Alternatively, you can manually delete the “autogenerated by docstring-gen library” (starting from the !!! note until the end) text from the classes and functions for which you think the auto-generated docstring is appropriate, and then re-run the command using the -f flag to update the remaining auto-generated docstrings.

In addition to the -f and --no-include-auto-gen-txt flags, you can also customize the behavior by adjusting other parameters such as --model, --temperature, etc., For more information on these options and how to use them, please refer to the OpenAI’s documentation.

Jupyter notebook extension

We have created a user-friendly notebook extension for the docstring-gen library. This extension provides a convenient way to document your code cell-by-cell, rather than having to document the entire notebook all at once. To install the extension, simply run the following commands in your terminal:

Note: Please ensure jupyter-contrib-nbextensions. is installed before installing the docstring-gen library extension

jupyter nbextension install https://github.com/airtai/jupyter-docstring-gen/archive/main.zip --user
jupyter nbextension enable jupyter-docstring-gen-main/jupyter-docstring-gen

After successful installation, you will see a new button on your jupyter notebook toolbar. This button allows you to easily generate docstrings for your Python code and improve your documentation.

For more detailed information, please refer to this link.

Copyright

Copyright © 2023 onwards airt technologies ltd, Inc.

License

This project is licensed under the terms of the Apache License 2.0

docstring-gen's People

Contributors

davorrunje avatar harishmohanraj avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

docstring-gen's Issues

Create a CLI command to generate docstring

  • Write a function to read and write notebook cells using AST
  • Add support for python files
  • Write a function to use open AI model to generate docstring for functions and classes
  • Handle rate limits
  • Wrap the above two into a CLI command 'docstring gen'

Will not connect, ever

I pip-installed this to experiment with it, created an account and API key, and all I get, ever, is:

Note: OpenAI's API rate limit reached. Command will automatically retry in...

goes through the 10 tries, with backoff, before it gives up. Repeat, ad infinitum.

I know this isn't exactly a "bug in the module code", but this does not appear usable as it depends on a resource that is apparently permanently unavailable.

nbdev-mkdocs issue

  • Fix openAI version in docstring-gen
  • Release docstring-gen RC version
  • Update docstring-gen version in nbdev-mkdocs and release RC version
  • Release docstring-gen actual version
  • Release nbdev-mkdocs actual version
  • Reply to the Issue

Add Language Support

It would be nice if there were multi-language support.

We work in German and English docstrings do not work for us.

From experience this could be as simple as having one English-based prompt and adding a setting for the language and depending on the language set in settings use AI to translate the prompt to the set other language. That way the prompts only need to be written once.

This also would open the possibility of having multilanguage support for the docstrings. Essentially giving people, the possibility of creating a version of the repo with English docstrings and others to open up documentation to people who do not speak English.

Add support for local AI

Using OpenAI on larger codebases and rerunning this often could cause no small cost and also might prevent people from using it.

Ollama has added full support for the OpenAI API for running local models. An option to use a local model would be nice.

relevant link to Ollama:
https://ollama.com/blog/openai-compatibility

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.