Package: docstring-auditor
Docstring AuditorMeetDocstring Auditor, your go-to solution for maintaining precise and up-to-date Python code documentation.
Tired of misleading or outdated docstrings? Docstring Auditor harnesses the power of large language models to analyze and critique your docstrings,
ensuring they align with your code's true purpose. Accessible to both experts and novices,
Docstring Auditor is your ultimate companion for clear, concise, and informative docstrings.
Say hello to better code documentation!MotivationRecognizing the need for a reliable tool to address the challenge of keeping code documentation in sync with evolving codebases, we developed Docstring Auditor to tackle this issue head-on. Our motivation was to create an accessible, user-friendly solution that empowers developers to maintain clear and up-to-date documentation with ease, enhancing their workflow and reducing misunderstandings.Docstring Auditor leverages the advanced capabilities of GPT-4, a powerful language model designed to deeply understand both code and natural language. By incorporating GPT-4 into our tool, Docstring Auditor examines the docstrings in your Python code, identifying discrepancies between the documentation and the actual code implementation. The analysis covers errors, warnings, and potential improvements, providing valuable critiques and suggestions to help you keep your documentation accurate and coherent. Docstring Auditor not only ensures that technical details, such as variables and types, are consistent, but it also verifies that the docstrings' meanings are in harmony with the code's functionality.With Docstring Auditor, you can trust that your documentation stays relevant, informative, and accessible to all members of your team, making collaboration smoother and more efficient than ever before.Docstring Auditorcan be utilized as aGitHub Action,
aDocker container,command-line tool,
orPython package.FeaturesAnalyzes Python functions' docstrings in a given fileIdentifies errors, warnings, and possible improvementsProvides detailed critiques and suggestions for better docstringsPowered by OpenAI's GPT for accurate and insightful analysisEasy to use command-line interfaceExample of Docstring Auditor in ActionLet's say you have a Python file called example.py with the following content:defcompute(a,b):"""Add two numbers.Parameters----------a : int or floatThe first number to be added or from which 'b' will be subtracted.b : int or floatThe second number to be added or subtracted.Returns-------int or floatThe result of the addition operation."""ifa>0:returna+belse:returna-bTo analyze the docstring of the add function, run:docstring-auditorexample.pyDocstring Auditor will then provide you with a detailed analysis of the docstring, including any errors, warnings, and suggestions for improvement.
The output may look like...Processingfunction1of1...
--------------------------------------------------------------------------------
Anerrorwasfoundinthefunction:compute

Thedocstringstatesthatthefunctionaddstwonumbers,butthecodealsoperformssubtractionif'a'islessthanorequalto0.Thedocstringshouldaccuratelydescribebothadditionandsubtractionoperations.

Awarningwasfoundinthefunction:compute

Thedocstringdoesnotfollowthenumpydocstylecompletely.Thesummarylineshouldbeaone-linesummary,andtheextendeddescriptionshouldbeprovidedinaseparateparagraph.

Aproposedsolutiontotheseconcernsis:"""Add or subtract two numbers based on the value of 'a'.This function performs addition if 'a' is greater than 0, and subtraction if 'a' is less than or equal to 0.Parameters----------a : int or floatThe first number to be added or from which 'b' will be subtracted.b : int or floatThe second number to be added or subtracted.Returns-------int or floatThe result of the addition or subtraction operation."""ParametersOptionTypeDefaultPurposepathPathfileThe path to the .py file or directory to analyze the functions' docstrings.--ignore-dirsString"tests"A list of directory names to ignore while processing .py files. Separate multiple directories with a space.--error-on-warningsBoolFalseIf true, warnings will be treated as errors and included in the exit code count.--modelString"gpt-4"The OpenAI model to use for docstring analysis. Default is 'gpt-4'.--code-block-nameString""The name of the block you wanted audited. Leave blank to audit all code blocks.--auto-fixBoolFalseAutomatically apply the suggestions to the code. Only applied for errors, not warnings.GitHub ActionDocstring Auditor can be used as a GitHub Action to automatically analyze the docstrings in your Python codebase.
To use Docstring Auditor as a GitHub Action, add the following to your workflow file:-name:Docstring Auditoruses:agencyenterprise/docstring-auditor@mainwith:openaiApiKey:${{ secrets.OPENAI_API_KEY }}path:.code-block-name:docstring_auditormodel:gpt-4ignore-dirs:testsauto-fix:falseFor an example of how to use Docstring Auditor,see this workflow.DockerDocstring Auditor can be used with DockerInstallDockerRun the following command:# If your code lives in the directory /Path/to/code# And you wish to analyse all files in that directorydockerrun-it--rm-eOPENAI_API_KEY=sk-XXXX-v/Path/to/code:/repodocstring-auditor# If your code lives in the directory /Path/to/code# And you wish to analyse a file called module/file.pydockerrun-it--rm-eOPENAI_API_KEY=sk-XXXX-v/Path/to/code:/repodocstring-auditormodule/file.pyUsageIf you use the docker command above, Docstring Auditor will analyse all python files in your directory.
If you wish for it to analyse a single file, pass in the file name with the repo prefix.
For example, to analyse the file insrc/module/file.py...dockerrun-it--rm-eOPENAI_API_KEY=sk-XXXX-v/Path/to/code:/repodocstring-auditorsrc/module/file.pyThe tool will then analyze the functions' docstrings in the specified file and display the critiques and suggestions for improvement.Local InstallationYou can also run Docstring Auditor locally by following these steps:InstallPython 3.6+InstallGitClone the repository:git clone git@github.com:agencyenterprise/docstring-auditor.gitSetup hatch:pip install hatchRun the packagehatch run docstring-auditor /path/to/your/python_file.pyLimitationsThere is currently no checking for malformed json from GPT4. Occasionaly, GPT4 will return a bad json and the program will crash.There is no rate limiting on the GPT4 calls.ContributingWe welcome contributions to Docstring Auditor! If you'd like to contribute, please fork the repository and submit a pull request with your changes. We also appreciate bug reports and feature requests submitted through the GitHub issues page.