docstring-gen
================
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
<b>Instantly improve the documentation of your Python code with
Codex.</b>
------------------------------------------------------------------------
  
------------------------------------------------------------------------
**docstring-gen** is an easy-to-use Python library that uses
<a href = "https://beta.openai.com/docs/models/codex" target="_blank">OpenAI’s
Codex model</a> to automatically generate
<a href="https://google.github.io/styleguide/pyguide.html" target = "_blank">Google-style
docstrings</a> 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.
``` shell
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
<a href="https://beta.openai.com/account/api-keys" target="_blank">create
an API key for OpenAI</a>.
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:
``` shell
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:
``` python
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:
``` python
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.
``` shell
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.
``` shell
docstring_gen {source_file_or_directory} -f --no-include-auto-gen-txt
```
Now the docstring for the above function will look similar to:
``` python
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
<a href="https://beta.openai.com/docs/api-reference/completions/create" target="_blank">OpenAI’s
documentation</a>.
### 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
<a href="https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/install.html" target="_blank">jupyter-contrib-nbextensions</a>.
is installed before installing the docstring-gen library extension
``` shell
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
<a href="https://github.com/airtai/jupyter-docstring-gen" target="_blank">link</a>.
## Copyright
Copyright © 2023 onwards airt technologies ltd, Inc.
## License
This project is licensed under the terms of the
<a href="https://github.com/airtai/docstring-gen/blob/main/LICENSE" target="_blank">Apache
License 2.0</a>
Raw data
{
"_id": null,
"home_page": "https://github.com/airtai/docstring-gen",
"name": "docstring-gen",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "nbdev jupyter notebook python mkdocs material docstring generator",
"author": "airt",
"author_email": "info@airt.ai",
"download_url": "https://files.pythonhosted.org/packages/9d/af/c4c86e42d65fc1a13e0e97fc49496ce26ddf650aa0e95b611d878413e1d0/docstring-gen-0.4.0.tar.gz",
"platform": null,
"description": "docstring-gen\n================\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n<b>Instantly improve the documentation of your Python code with\nCodex.</b>\n\n------------------------------------------------------------------------\n\n  \n\n\n\n\n\n\n\n------------------------------------------------------------------------\n\n**docstring-gen** is an easy-to-use Python library that uses\n<a href = \"https://beta.openai.com/docs/models/codex\" target=\"_blank\">OpenAI\u2019s\nCodex model</a> to automatically generate\n<a href=\"https://google.github.io/styleguide/pyguide.html\" target = \"_blank\">Google-style\ndocstrings</a> for Python codebase. The library is capable of reading\nboth Jupyter notebooks and Python files, and seamlessly adds meaningful\ndocstrings to classes and functions that lack documentation. By using\n**docstring-gen**, developers can automatically generate docstrings for\ntheir codebase, resulting in time savings and improved documentation\nquality.\n\n## Install\n\n**docstring-gen** can be installed by running the command below. This\npackage requires Python 3.7 or higher to work.\n\n``` shell\npip install docstring-gen\n```\n\nIf the installation was successful, you should now have\n**docstring-gen** installed on your system. To see a full list of\nsettings, run `docstring_gen --help`\n\nIf you\u2019re excited to try the latest version, you can install it directly\nfrom GitHub by using the command:\n`pip install git+https://github.com/airtai/docstring-gen`\n\n## How to use\n\nThe **docstring-gen** library uses OpenAI\u2019s Codex model to generate\ndocstrings for your Python classes and functions. In order to use the\nlibrary, you\u2019ll need to\n<a href=\"https://beta.openai.com/account/api-keys\" target=\"_blank\">create\nan API key for OpenAI</a>.\n\nOnce you have your API key, store it in the **OPENAI_API_KEY**\nenvironment variable. This is a necessary step for the library to work.\n\nTo get started right away with sensible defaults, run:\n\n``` shell\ndocstring_gen {source_file_or_directory}\n```\n\nThis will automatically add meaningful, Google-style docstrings to the\nPython classes and functions in the {source_file_or_directory} that do\nnot already have one.\n\nFor example, a function like below without the docstring:\n\n``` python\ndef concatenate_strings(s1: str, s2: str) -> str:\n if not isinstance(s1, str) or not isinstance(s2, str):\n raise TypeError(\"Both arguments should be strings.\")\n return s1 + s2\n```\n\nwill become similar to:\n\n``` python\ndef concatenate_strings(s1: str, s2: str) -> str:\n \"\"\"Concatenate two strings.\n\n Args:\n s1: First string\n s2: Second string\n\n Returns:\n The concatenated string\n\n Raises:\n TypeError: If s1 or s2 is not a string\n\n !!! note\n\n The above docstring is autogenerated by docstring-gen library (https://docstring-gen.airt.ai)\n \"\"\"\n if not isinstance(s1, str) or not isinstance(s2, str):\n raise TypeError(\"Both arguments should be strings.\")\n return s1 + s2\n```\n\nIf you wish to regenerate the docstrings, you can re-run the command\nwith the `-f` flag, which will remove the previous auto-generated\ndocstrings and replace them with new ones.\n\n``` shell\ndocstring_gen {source_file_or_directory} -f\n```\n\n**Note**: The default behavior of the library is to add docstrings only\nto functions and classes that are missing them. So, if you do not\nprovide the `-f` flag when re-running the command, the library will not\nreplace previously auto-generated docstrings, assuming that the\nfunctions already have them.\n\nIf you prefer not to include the text **\u201cautogenerated by docstring-gen\nlibrary\u201d** in the generated docstrings, you can use the\n`--no-include-auto-gen-txt` flag when running the command.\n\n``` shell\ndocstring_gen {source_file_or_directory} -f --no-include-auto-gen-txt\n```\n\nNow the docstring for the above function will look similar to:\n\n``` python\ndef concatenate_strings(s1: str, s2: str) -> str:\n \"\"\"Concatenate two strings.\n\n Args:\n s1: First string\n s2: Second string\n\n Returns:\n The concatenated string\n\n Raises:\n TypeError: If s1 or s2 is not a string\n \"\"\"\n if not isinstance(s1, str) or not isinstance(s2, str):\n raise TypeError(\"Both arguments should be strings.\")\n return s1 + s2\n```\n\n**Important**: The library uses the text **\u201cautogenerated by\ndocstring-gen library\u201d** to identify which docstrings were generated by\nthe library. When the `--no-include-auto-gen-txt` flag is used, this\ntext will not be included in the generated docstrings. As a result, when\nre-running the command with the `-f` flag, these docstrings will not be\nreplaced.\u201d\n\nAlternatively, you can manually delete the **\u201cautogenerated by\ndocstring-gen library\u201d** (starting from the !!! note until the end) text\nfrom the classes and functions for which you think the auto-generated\ndocstring is appropriate, and then re-run the command using the `-f`\nflag to update the remaining auto-generated docstrings.\n\nIn addition to the `-f` and `--no-include-auto-gen-txt` flags, you can\nalso customize the behavior by adjusting other parameters such as\n`--model`, `--temperature`, etc., For more information on these options\nand how to use them, please refer to the\n<a href=\"https://beta.openai.com/docs/api-reference/completions/create\" target=\"_blank\">OpenAI\u2019s\ndocumentation</a>.\n\n### Jupyter notebook extension\n\nWe have created a user-friendly notebook extension for the docstring-gen\nlibrary. This extension provides a convenient way to document your code\ncell-by-cell, rather than having to document the entire notebook all at\nonce. To install the extension, simply run the following commands in\nyour terminal:\n\n**Note**: Please ensure\n<a href=\"https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/install.html\" target=\"_blank\">jupyter-contrib-nbextensions</a>.\nis installed before installing the docstring-gen library extension\n\n``` shell\njupyter nbextension install https://github.com/airtai/jupyter-docstring-gen/archive/main.zip --user\njupyter nbextension enable jupyter-docstring-gen-main/jupyter-docstring-gen\n```\n\nAfter successful installation, you will see a new button on your jupyter\nnotebook toolbar. This button allows you to easily generate docstrings\nfor your Python code and improve your documentation.\n\n\n\nFor more detailed information, please refer to this\n<a href=\"https://github.com/airtai/jupyter-docstring-gen\" target=\"_blank\">link</a>.\n\n## Copyright\n\nCopyright \u00a9 2023 onwards airt technologies ltd, Inc.\n\n## License\n\nThis project is licensed under the terms of the\n<a href=\"https://github.com/airtai/docstring-gen/blob/main/LICENSE\" target=\"_blank\">Apache\nLicense 2.0</a>\n\n\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Generate docstrings using OpenAI's Codex model.",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/airtai/docstring-gen"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python",
"mkdocs",
"material",
"docstring",
"generator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6523d73b501d21241e1e2bd06b8e79a2b037f1d1caf345181430ea9779b699c",
"md5": "c1d7a320a7f0afe9d0c812c28ab0c57f",
"sha256": "b51d067016bd664c457de66cefbb933a38b99aac9c1cde44f3b1e53c70539d49"
},
"downloads": -1,
"filename": "docstring_gen-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1d7a320a7f0afe9d0c812c28ab0c57f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16736,
"upload_time": "2024-02-21T04:41:38",
"upload_time_iso_8601": "2024-02-21T04:41:38.913868Z",
"url": "https://files.pythonhosted.org/packages/d6/52/3d73b501d21241e1e2bd06b8e79a2b037f1d1caf345181430ea9779b699c/docstring_gen-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9dafc4c86e42d65fc1a13e0e97fc49496ce26ddf650aa0e95b611d878413e1d0",
"md5": "c90eb0f48123bfae7700fcf91ab563d3",
"sha256": "4bfac8eea01ff4ce4334974ed95ba155bba1c7c7cc7ce8bcee2d638f061da977"
},
"downloads": -1,
"filename": "docstring-gen-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "c90eb0f48123bfae7700fcf91ab563d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18631,
"upload_time": "2024-02-21T04:41:40",
"upload_time_iso_8601": "2024-02-21T04:41:40.602970Z",
"url": "https://files.pythonhosted.org/packages/9d/af/c4c86e42d65fc1a13e0e97fc49496ce26ddf650aa0e95b611d878413e1d0/docstring-gen-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-21 04:41:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "airtai",
"github_project": "docstring-gen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docstring-gen"
}
JSON
