Docstring Auditor

欢迎使用 Docstring Auditor，这是您维护精确和最新Python代码文档的必备解决方案。厌倦了误导或不准确的文档字符串？Docstring Auditor利用大型语言模型的力量来分析和批评您的文档字符串，确保它们与代码的真实目的保持一致。Docstring Auditor既适用于专家也适用于新手，是您制作清晰、简洁和信息丰富的文档字符串的终极伴侣。欢迎来到更好的代码文档时代！

动机

认识到需要一种可靠的工具来解决代码文档与不断发展的代码库同步的挑战，我们开发了Docstring Auditor来直接解决这个问题。我们的动机是创建一个易于访问、用户友好的解决方案，使开发者能够轻松地维护清晰和最新的文档，从而提高他们的工作效率并减少误解。

Docstring Auditor利用了GPT-4的高级功能，这是一种旨在深刻理解代码和自然语言的有效语言模型。通过将GPT-4纳入我们的工具，Docstring Auditor检查您的Python代码中的文档字符串，识别文档与实际代码实现之间的差异。分析包括错误、警告和潜在改进，提供宝贵的批评和建议，帮助您保持文档的准确性和一致性。Docstring Auditor不仅确保技术细节（如变量和类型）保持一致，还验证文档字符串的含义与代码的功能相协调。

使用Docstring Auditor，您可以相信您的文档始终与团队所有成员保持相关性、信息性和可访问性，从而使协作比以往任何时候都更加顺畅和高效。

Docstring Auditor可以作为GitHub Action、Docker容器、命令行工具或Python包使用。

功能

• 分析指定文件中Python函数的docstring
• 识别错误、警告和可能的改进
• 提供对更好的docstring的详细评价和建议
• 由OpenAI的GPT提供准确且富有洞察力的分析
• 易于使用的命令行界面

Docstring Auditor的实际应用示例

假设您有一个名为example.py的Python文件，其内容如下

def compute(a, b):
    """
    Add two numbers.

    Parameters
    ----------
    a : int or float
        The first number to be added or from which 'b' will be subtracted.
    b : int or float
        The second number to be added or subtracted.

    Returns
    -------
    int or float
        The result of the addition operation.
    """
     if a > 0:
        return a + b
     else:
        return a - b

要分析add函数的docstring，请运行

docstring-auditor example.py

Docstring Auditor将为您提供对docstring的详细分析，包括任何错误、警告和改进建议。输出可能如下所示...

Processing function 1 of 1...
--------------------------------------------------------------------------------
An error was found in the function: compute

The docstring states that the function adds two numbers, but the code also performs subtraction if 'a' is less than or equal to 0. The docstring should accurately describe both addition and subtraction operations.

A warning was found in the function: compute

The docstring does not follow the numpydoc style completely. The summary line should be a one-line summary, and the extended description should be provided in a separate paragraph.

A proposed solution to these concerns is:

"""
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 float
    The first number to be added or from which 'b' will be subtracted.
b : int or float
    The second number to be added or subtracted.

Returns
-------
int or float
    The result of the addition or subtraction operation.
"""

参数

GitHub Action

Docstring Auditor可以作为GitHub Action使用来自动分析Python代码库中的docstring。要将Docstring Auditor作为GitHub Action使用，请将以下内容添加到您的workfile中

  - name: Docstring Auditor
    uses: agencyenterprise/docstring-auditor@main
    with:
      openaiApiKey: ${{ secrets.OPENAI_API_KEY }}
      path: .
      code-block-name: docstring_auditor
      model: gpt-4
      ignore-dirs: tests
      auto-fix: false

有关如何使用Docstring Auditor的示例，请参阅此工作流程。

Docker

Docstring Auditor可以与Docker一起使用

1. 安装Docker
2. 运行以下命令

# If your code lives in the directory /Path/to/code
# And you wish to analyse all files in that directory
docker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor

# If your code lives in the directory /Path/to/code
# And you wish to analyse a file called module/file.py
docker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor module/file.py

用法

如果您使用上述docker命令，Docstring Auditor将分析您目录中的所有Python文件。如果您希望它分析单个文件，请使用repo前缀传递文件名。例如，要分析src/module/file.py中的文件...

docker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor src/module/file.py

该工具将分析指定文件中的函数docstring并显示批评和建议。

本地安装

您还可以按照以下步骤在本地运行Docstring Auditor

1. 安装Python 3.6+
2. 安装Git
3. 克隆存储库：git clone git@github.com:agencyenterprise/docstring-auditor.git
4. 设置hatch：pip install hatch
5. 运行包：hatch run docstring-auditor /path/to/your/python_file.py

限制

1. 目前没有检查GPT4的格式不正确的json。偶尔，GPT4会返回不良的json，程序会崩溃。
2. 没有对GPT4调用的速率限制。

贡献

我们欢迎对Docstring Auditor的贡献！如果您想贡献，请fork存储库并提交包含您更改的pull request。我们也很感激通过GitHub issues页面提交的bug报告和功能请求。