| Name | agent-docstrings JSON |
| Version |
1.3.4
JSON |
| download |
| home_page | None |
| Summary | A command-line tool to auto-generate and update file-level docstrings summarizing classes and functions. Useful for maintaining a high-level overview of your files, especially in projects with code generated or modified by AI assistants. |
| upload_time | 2025-07-08 09:48:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 Artemonim
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
docstrings
documentation
ai
developer-tools
automation
code-generator
maintainability
code-quality
static-analysis
pre-commit
linter
summarize-code
code-navigation
refactoring
python
java
kotlin
go
powershell
delphi
typescript
javascript
csharp
c++
c
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!-- ain badges -->
[](https://badge.fury.io/py/agent-docstrings)
[](https://pypi.org/project/agent-docstrings/)
[](https://opensource.org/licenses/MIT)
<!-- GitHub stats -->
[](https://github.com/Artemonim/AgentDocstrings)
[](https://github.com/Artemonim/AgentDocstrings)
[](https://github.com/Artemonim/AgentDocstrings/actions)
<!-- Code Quality -->
[](https://github.com/psf/black)
[](https://mypy-lang.org/)
[](https://codecov.io/gh/Artemonim/AgentDocstrings)
# Agent Docstrings: Automatic Code Summaries
**Agent Docstrings** is a command-line tool that automatically generates and maintains a "Table of Contents" at the top of your source files. It scans for classes, functions, and methods, creating a summary that provides a high-level overview of the file's structure.
<img src="Doc/AgentDocstringsExample130.webp" alt="Agent Docstrings Demo" width="600" style="border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);" />
This is especially useful for AI-Agents, helping them solve the "cold start" problem of quickly understanding and navigating large, unfamiliar codebases.
---
## Table of Contents
- [Supported Languages](#supported-languages)
- [Why Use Agent Docstrings?](#why-use-agent-docstrings)
- [Features](#features)
- [Examples](#examples)
- [Platform Compatibility](#platform-compatibility)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Limitations and Nuances](#limitations-and-nuances)
- [Integration with Development Workflow](#integration-with-development-workflow)
- [Development](#development)
- [Support the Project](#support-the-project)
- [Contributing](#contributing)
- [License](#license)
- [Changelog](#changelog)
---
## Supported Languages
| Language | File Extensions | Features |
| ---------- | ----------------------------------- | ------------------------------ |
| Python | `.py` | Classes, functions, methods |
| Java | `.java` | Classes, methods |
| Kotlin | `.kt` | Classes, functions |
| Go | `.go` | Functions, methods |
| PowerShell | `.ps1`, `.psm1` | Functions |
| Delphi | `.pas` | Classes, procedures, functions |
| C | `.c`, `.h` | Functions |
| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx`, `.h` | Functions, classes |
| C# | `.cs` | Classes, methods |
| JavaScript | `.js`, `.jsx` | Functions, classes |
| TypeScript | `.ts`, `.tsx` | Functions, classes |
## Why Use Agent Docstrings?
Imagine an AI agent tasked with modifying a large, unfamiliar codebase. Its first step is to read a file to get its bearings. What if the first thing it saw was a perfect summary?
#### Without Agent Docstrings: The "Blind" Approach
An AI agent opens a file and has no initial context. To understand the file's structure, it must:
1. Read a large chunk of the file.
2. Use tools like `grep_tool` or other search methods to find function and class definitions.
3. Analyze and piece together the results to build a mental map of the file.
This process is slow, api-intensive, and prone to error.
#### With Agent Docstrings: The "Map-First" Approach
The agent opens the same file. The very first thing it reads is a "Table of Contents" generated by this tool. This provides immediate, critical advantages:
- **Solves the "Cold Start" Problem**: The agent instantly understands the file's layout, classes, and functions without any prior knowledge. The docstring acts as a "map" for the new territory, providing an immediate entry point for analysis.
- **Dramatically Boosts Efficiency**: Gaining this structural overview is a single `read_tool` operation. This is far more efficient than performing multiple searches and analyses to build the same context from scratch.
- **Enhances Situational Awareness**: With a clear overview from the start, the agent's subsequent actions (like targeted code searches or modifications) become more precise and intelligent. Knowing that a function `integrate_user_data` exists allows for a much more focused approach than a broad search for "user data".
In short, **Agent Docstrings** gives an AI a crucial head start, turning a slow, investigative process into a quick, informed action.
## Features
- **Multi-language support**: Works with a wide range of popular programming languages.
- **Automatic discovery**: Recursively scans directories for source files to process.
- **Smart filtering**: Automatically respects `.gitignore` files and allows for custom ignore (`.agent-docstrings-ignore`) and include (`.agent-docstrings-include`) files for fine-grained control.
- **Incremental updates**: Designed to be fast, it only modifies files when changes to the code structure are detected.
- **Robust Parsers**: Uses reliable AST (Abstract Syntax Tree) parsers for Python and Go, and intelligent regex-based parsing for other languages.
- **CLI interface**: A simple and easy-to-use command-line tool for manual runs or CI/CD integration.
- **Extensively Tested**: High reliability is ensured by a comprehensive suite of over 140 tests, covering everything from individual parsers (unit tests) to full command-line behavior (end-to-end tests).
## Examples
### Python Example
Before:
```python
def calculate_fibonacci(n):
if n <= 1:
return n
return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)
class MathUtils:
def add(self, a, b):
return a + b
```
After:
```python
"""
--- AUTO-GENERATED DOCSTRING ---
Table of content is automatically generated by Agent Docstrings v1.3.0
Classes/Functions:
- MathUtils (line 18):
- add(a, b) (line 19)
- Functions:
- calculate_fibonacci(n) (line 13)
--- END AUTO-GENERATED DOCSTRING ---
"""
def calculate_fibonacci(n):
if n <= 1:
return n
return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)
class MathUtils:
def add(self, a, b):
return a + b
```
## Platform Compatibility
This tool is compatible with:
- **Python**: 3.10, 3.11, 3.12, and 3.13
- **Go**: >=1.22 (required only for building the Go parser during package development)
- No dependency on external Python libraries at runtime
## Installation
### From PyPI (recommended)
```bash
pip install agent-docstrings
```
### From source
```bash
git clone https://github.com/Artemonim/agent-docstrings.git
cd agent-docstrings
pip install -e .
```
## Usage
### Processing paths
You can process one or more directories, files, or a mix of both.
Process a directory:
```bash
agent-docstrings src/
```
Process a single file:
```bash
agent-docstrings src/main.py
```
Process multiple paths:
```bash
agent-docstrings src/ tests/ lib/utils.py
```
### With verbose output
```bash
agent-docstrings src/ --verbose
```
### Using as a Python module
```python
from agent_docstrings.core import discover_and_process_files
# Process a mix of files and directories
discover_and_process_files(["src/", "lib/utils.py"], verbose=True)
```
## Configuration
### Gitignore Integration
The tool automatically reads and respects `.gitignore` files in your project directory and its parents. Files and directories ignored by git will also be ignored by the docstring generator.
### Blacklist (Ignore files)
You can create a gitignore-like `.agent-docstrings-ignore` file in your project root to specify files and directories to ignore:
### Whitelist (Only process specific files)
You can create a gitignore-like `.agent-docstrings-include` file to only process specific files:
```
# Only process main source code
src/*.py
lib/*.py
agent_docstrings/*.py
```
**Note**: If a whitelist file exists and is not empty, ONLY files matching the whitelist patterns will be processed.
## Limitations and Nuances
It is important to understand the nuances of this tool to use it effectively. The quality and method of code parsing vary significantly by language.
- **Table of Contents, Not Full Documentation**: The generator does not create detailed, explanatory docstrings. Instead, it generates a file-level comment block that acts as a "Table of Contents" listing the functions and classes found in the file. This provides a quick overview of the file's structure.
- **Language-Dependent Parsing Quality**: The reliability of the parser is highly dependent on the target language.
- **Robust AST-Based Parsing (Python, Go)**: For Python and Go, the tool uses native Abstract Syntax Tree (AST) parsers. This approach is highly accurate and robustly handles complex syntax, multiline definitions, and unconventional formatting.
- **Regex-Based Parsing (Other Languages)**: For other languages (C++, C#, Java, JavaScript, TypeScript, Kotlin, PowerShell, Delphi), the generator relies on regular expressions and simplified scope analysis (brace counting). This method is inherently more fragile and may fail or produce incorrect results with:
- **Multiline Definitions**: Function or class signatures that span multiple lines.
- **Complex Syntax**: Advanced language features like C++ templates, decorators on separate lines, or complex default parameter values.
- **Unconventional Formatting**: Code that does not follow common formatting standards.
- **Scope Confusion**: The brace-counting mechanism can be easily confused by comments or strings containing `{` or `}` characters, leading to incorrect structure detection.
- **In-Place File Modification**: The tool modifies files directly. It is designed to correctly remove its own previously generated headers, but it might struggle with files that have very complex, pre-existing header comments, potentially leading to incorrect placement of the new header.
## Integration with Development Workflow
### Pre-commit Hook
Add to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: local
hooks:
- id: agent-docstrings
name: Generate docstrings
entry: agent-docstrings
language: system
files: \.(py|java|kt|go|ps1|psm1|pas|js|jsx|ts|tsx|cs|cpp|cxx|cc|hpp|h|c)$
pass_filenames: false
args: [src/]
```
### CI/CD Integration
```yaml
# GitHub Actions example
- name: Generate docstrings
run: |
pip install agent-docstrings
agent-docstrings src/
# Check if any files were modified
git diff --exit-code || (echo "Docstrings need updating" && exit 1)
```
## Development
### Setting up development environment
```bash
git clone https://github.com/Artemonim/agent-docstrings.git
cd agent-docstrings
pip install -e .[dev]
```
### Running tests
```bash
pytest tests/ -v
```
### Code formatting
```bash
black agent_docstrings/
```
### Type checking
```bash
mypy agent_docstrings/
```
### Version Bumping
This project uses [bump-my-version](https://github.com/callowayproject/bump-my-version) for version management. To create a new version, use the following commands after installing the development dependencies (`pip install -e .[dev]`):
- **Patch release (e.g., 1.0.1 -> 1.0.2):**
```bash
bump-my-version patch
```
- **Minor release (e.g., 1.0.2 -> 1.1.0):**
```bash
bump-my-version minor
```
- **Major release (e.g., 1.1.0 -> 2.0.0):**
```bash
bump-my-version major
```
The tool is configured in `pyproject.toml` to automatically update the version string in `agent_docstrings/__init__.py`, `pyproject.toml`, and `CHANGELOG.md`.
**Note**: Running `bump-my-version`, you need to create a release branch and a pull request to `master`. The process of tagging, creating a GitHub Release, and publishing to PyPI is automated. For full details, see the [Contribution Guide](CONTRIBUTING.md).
## Support the Project
Agent Docstrings is an independent open-source project. If you find this tool useful and want to support its ongoing development, your help would be greatly appreciated.
Here are a few ways you can contribute:
- **Give a Star:** The simplest way to show your support is to star the project on [GitHub](https://github.com/Artemonim/AgentDocstrings)! It increases the project's visibility.
- **Support My Work:** Your financial contribution helps me dedicate more time to improving this tool and creating other open-source projects. On my [**Boosty page**](https://boosty.to/artemonim), you can:
- Make a **one-time donation** to thank me for this specific project.
- Become a **monthly supporter** to help all of my creative endeavors.
- **Try a Recommended Tool:** This project was inspired by my work with LLMs. If you're looking for a great service to work with multiple neural networks, check out [**Syntx AI**](https://t.me/syntxaibot?start=aff_157453205). Using my referral link is another way to support my work at no extra cost to you.
Thank you for your support!
## Contributing
We welcome contributions! Please see our [**Contribution Guide**](CONTRIBUTING.md) for detailed instructions on how to get started, our development workflow, and coding standards.
In short:
1. Fork the repo and create your branch from `dev`.
2. Add your feature or fix.
3. Add/update tests.
4. Update `CHANGELOG.md`.
5. Submit a pull request to `dev`.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.
## Support
- **Issues**: [GitHub Issues](https://github.com/Artemonim/agent-docstrings/issues)
- **Documentation**: [GitHub README](https://github.com/Artemonim/agent-docstrings#readme)
- **Source Code**: [GitHub Repository](https://github.com/Artemonim/agent-docstrings)
Raw data
{
"_id": null,
"home_page": null,
"name": "agent-docstrings",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Artemonim <Artemonim@yandex.ru>",
"keywords": "docstrings, documentation, ai, developer-tools, automation, code-generator, maintainability, code-quality, static-analysis, pre-commit, linter, summarize-code, code-navigation, refactoring, python, java, kotlin, go, powershell, delphi, typescript, javascript, csharp, c++, c",
"author": null,
"author_email": "Artemonim <Artemonim@yandex.ru>",
"download_url": "https://files.pythonhosted.org/packages/cd/02/f614591ccdf0279f01f728e9622367d6aa3139b3caa431ca93ef9967c91d/agent_docstrings-1.3.4.tar.gz",
"platform": null,
"description": "<!-- ain badges -->\n\n[](https://badge.fury.io/py/agent-docstrings)\n[](https://pypi.org/project/agent-docstrings/)\n[](https://opensource.org/licenses/MIT)\n\n<!-- GitHub stats -->\n\n[](https://github.com/Artemonim/AgentDocstrings)\n[](https://github.com/Artemonim/AgentDocstrings)\n[](https://github.com/Artemonim/AgentDocstrings/actions)\n\n<!-- Code Quality -->\n\n[](https://github.com/psf/black)\n[](https://mypy-lang.org/)\n[](https://codecov.io/gh/Artemonim/AgentDocstrings)\n\n# Agent Docstrings: Automatic Code Summaries\n\n**Agent Docstrings** is a command-line tool that automatically generates and maintains a \"Table of Contents\" at the top of your source files. It scans for classes, functions, and methods, creating a summary that provides a high-level overview of the file's structure.\n\n<img src=\"Doc/AgentDocstringsExample130.webp\" alt=\"Agent Docstrings Demo\" width=\"600\" style=\"border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);\" />\n\nThis is especially useful for AI-Agents, helping them solve the \"cold start\" problem of quickly understanding and navigating large, unfamiliar codebases.\n\n---\n\n## Table of Contents\n\n- [Supported Languages](#supported-languages)\n- [Why Use Agent Docstrings?](#why-use-agent-docstrings)\n- [Features](#features)\n- [Examples](#examples)\n- [Platform Compatibility](#platform-compatibility)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Limitations and Nuances](#limitations-and-nuances)\n- [Integration with Development Workflow](#integration-with-development-workflow)\n- [Development](#development)\n- [Support the Project](#support-the-project)\n- [Contributing](#contributing)\n- [License](#license)\n- [Changelog](#changelog)\n\n---\n\n## Supported Languages\n\n| Language | File Extensions | Features |\n| ---------- | ----------------------------------- | ------------------------------ |\n| Python | `.py` | Classes, functions, methods |\n| Java | `.java` | Classes, methods |\n| Kotlin | `.kt` | Classes, functions |\n| Go | `.go` | Functions, methods |\n| PowerShell | `.ps1`, `.psm1` | Functions |\n| Delphi | `.pas` | Classes, procedures, functions |\n| C | `.c`, `.h` | Functions |\n| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx`, `.h` | Functions, classes |\n| C# | `.cs` | Classes, methods |\n| JavaScript | `.js`, `.jsx` | Functions, classes |\n| TypeScript | `.ts`, `.tsx` | Functions, classes |\n\n## Why Use Agent Docstrings?\n\nImagine an AI agent tasked with modifying a large, unfamiliar codebase. Its first step is to read a file to get its bearings. What if the first thing it saw was a perfect summary?\n\n#### Without Agent Docstrings: The \"Blind\" Approach\n\nAn AI agent opens a file and has no initial context. To understand the file's structure, it must:\n\n1. Read a large chunk of the file.\n2. Use tools like `grep_tool` or other search methods to find function and class definitions.\n3. Analyze and piece together the results to build a mental map of the file.\n This process is slow, api-intensive, and prone to error.\n\n#### With Agent Docstrings: The \"Map-First\" Approach\n\nThe agent opens the same file. The very first thing it reads is a \"Table of Contents\" generated by this tool. This provides immediate, critical advantages:\n\n- **Solves the \"Cold Start\" Problem**: The agent instantly understands the file's layout, classes, and functions without any prior knowledge. The docstring acts as a \"map\" for the new territory, providing an immediate entry point for analysis.\n- **Dramatically Boosts Efficiency**: Gaining this structural overview is a single `read_tool` operation. This is far more efficient than performing multiple searches and analyses to build the same context from scratch.\n- **Enhances Situational Awareness**: With a clear overview from the start, the agent's subsequent actions (like targeted code searches or modifications) become more precise and intelligent. Knowing that a function `integrate_user_data` exists allows for a much more focused approach than a broad search for \"user data\".\n\nIn short, **Agent Docstrings** gives an AI a crucial head start, turning a slow, investigative process into a quick, informed action.\n\n## Features\n\n- **Multi-language support**: Works with a wide range of popular programming languages.\n- **Automatic discovery**: Recursively scans directories for source files to process.\n- **Smart filtering**: Automatically respects `.gitignore` files and allows for custom ignore (`.agent-docstrings-ignore`) and include (`.agent-docstrings-include`) files for fine-grained control.\n- **Incremental updates**: Designed to be fast, it only modifies files when changes to the code structure are detected.\n- **Robust Parsers**: Uses reliable AST (Abstract Syntax Tree) parsers for Python and Go, and intelligent regex-based parsing for other languages.\n- **CLI interface**: A simple and easy-to-use command-line tool for manual runs or CI/CD integration.\n- **Extensively Tested**: High reliability is ensured by a comprehensive suite of over 140 tests, covering everything from individual parsers (unit tests) to full command-line behavior (end-to-end tests).\n\n## Examples\n\n### Python Example\n\nBefore:\n\n```python\ndef calculate_fibonacci(n):\n if n <= 1:\n return n\n return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)\n\nclass MathUtils:\n def add(self, a, b):\n return a + b\n```\n\nAfter:\n\n```python\n\"\"\"\n --- AUTO-GENERATED DOCSTRING ---\n Table of content is automatically generated by Agent Docstrings v1.3.0\n\n Classes/Functions:\n - MathUtils (line 18):\n - add(a, b) (line 19)\n - Functions:\n - calculate_fibonacci(n) (line 13)\n --- END AUTO-GENERATED DOCSTRING ---\n\"\"\"\ndef calculate_fibonacci(n):\n if n <= 1:\n return n\n return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)\n\nclass MathUtils:\n def add(self, a, b):\n return a + b\n```\n\n## Platform Compatibility\n\nThis tool is compatible with:\n\n- **Python**: 3.10, 3.11, 3.12, and 3.13\n- **Go**: >=1.22 (required only for building the Go parser during package development)\n\n- No dependency on external Python libraries at runtime\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install agent-docstrings\n```\n\n### From source\n\n```bash\ngit clone https://github.com/Artemonim/agent-docstrings.git\ncd agent-docstrings\npip install -e .\n```\n\n## Usage\n\n### Processing paths\n\nYou can process one or more directories, files, or a mix of both.\n\nProcess a directory:\n\n```bash\nagent-docstrings src/\n```\n\nProcess a single file:\n\n```bash\nagent-docstrings src/main.py\n```\n\nProcess multiple paths:\n\n```bash\nagent-docstrings src/ tests/ lib/utils.py\n```\n\n### With verbose output\n\n```bash\nagent-docstrings src/ --verbose\n```\n\n### Using as a Python module\n\n```python\nfrom agent_docstrings.core import discover_and_process_files\n\n# Process a mix of files and directories\ndiscover_and_process_files([\"src/\", \"lib/utils.py\"], verbose=True)\n```\n\n## Configuration\n\n### Gitignore Integration\n\nThe tool automatically reads and respects `.gitignore` files in your project directory and its parents. Files and directories ignored by git will also be ignored by the docstring generator.\n\n### Blacklist (Ignore files)\n\nYou can create a gitignore-like `.agent-docstrings-ignore` file in your project root to specify files and directories to ignore:\n\n### Whitelist (Only process specific files)\n\nYou can create a gitignore-like `.agent-docstrings-include` file to only process specific files:\n\n```\n# Only process main source code\nsrc/*.py\nlib/*.py\nagent_docstrings/*.py\n```\n\n**Note**: If a whitelist file exists and is not empty, ONLY files matching the whitelist patterns will be processed.\n\n## Limitations and Nuances\n\nIt is important to understand the nuances of this tool to use it effectively. The quality and method of code parsing vary significantly by language.\n\n- **Table of Contents, Not Full Documentation**: The generator does not create detailed, explanatory docstrings. Instead, it generates a file-level comment block that acts as a \"Table of Contents\" listing the functions and classes found in the file. This provides a quick overview of the file's structure.\n\n- **Language-Dependent Parsing Quality**: The reliability of the parser is highly dependent on the target language.\n\n - **Robust AST-Based Parsing (Python, Go)**: For Python and Go, the tool uses native Abstract Syntax Tree (AST) parsers. This approach is highly accurate and robustly handles complex syntax, multiline definitions, and unconventional formatting.\n\n - **Regex-Based Parsing (Other Languages)**: For other languages (C++, C#, Java, JavaScript, TypeScript, Kotlin, PowerShell, Delphi), the generator relies on regular expressions and simplified scope analysis (brace counting). This method is inherently more fragile and may fail or produce incorrect results with:\n - **Multiline Definitions**: Function or class signatures that span multiple lines.\n - **Complex Syntax**: Advanced language features like C++ templates, decorators on separate lines, or complex default parameter values.\n - **Unconventional Formatting**: Code that does not follow common formatting standards.\n - **Scope Confusion**: The brace-counting mechanism can be easily confused by comments or strings containing `{` or `}` characters, leading to incorrect structure detection.\n\n- **In-Place File Modification**: The tool modifies files directly. It is designed to correctly remove its own previously generated headers, but it might struggle with files that have very complex, pre-existing header comments, potentially leading to incorrect placement of the new header.\n\n## Integration with Development Workflow\n\n### Pre-commit Hook\n\nAdd to your `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: agent-docstrings\n name: Generate docstrings\n entry: agent-docstrings\n language: system\n files: \\.(py|java|kt|go|ps1|psm1|pas|js|jsx|ts|tsx|cs|cpp|cxx|cc|hpp|h|c)$\n pass_filenames: false\n args: [src/]\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions example\n- name: Generate docstrings\n run: |\n pip install agent-docstrings\n agent-docstrings src/\n # Check if any files were modified\n git diff --exit-code || (echo \"Docstrings need updating\" && exit 1)\n```\n\n## Development\n\n### Setting up development environment\n\n```bash\ngit clone https://github.com/Artemonim/agent-docstrings.git\ncd agent-docstrings\npip install -e .[dev]\n```\n\n### Running tests\n\n```bash\npytest tests/ -v\n```\n\n### Code formatting\n\n```bash\nblack agent_docstrings/\n```\n\n### Type checking\n\n```bash\nmypy agent_docstrings/\n```\n\n### Version Bumping\n\nThis project uses [bump-my-version](https://github.com/callowayproject/bump-my-version) for version management. To create a new version, use the following commands after installing the development dependencies (`pip install -e .[dev]`):\n\n- **Patch release (e.g., 1.0.1 -> 1.0.2):**\n ```bash\n bump-my-version patch\n ```\n- **Minor release (e.g., 1.0.2 -> 1.1.0):**\n ```bash\n bump-my-version minor\n ```\n- **Major release (e.g., 1.1.0 -> 2.0.0):**\n ```bash\n bump-my-version major\n ```\n\nThe tool is configured in `pyproject.toml` to automatically update the version string in `agent_docstrings/__init__.py`, `pyproject.toml`, and `CHANGELOG.md`.\n\n**Note**: Running `bump-my-version`, you need to create a release branch and a pull request to `master`. The process of tagging, creating a GitHub Release, and publishing to PyPI is automated. For full details, see the [Contribution Guide](CONTRIBUTING.md).\n\n## Support the Project\n\nAgent Docstrings is an independent open-source project. If you find this tool useful and want to support its ongoing development, your help would be greatly appreciated.\n\nHere are a few ways you can contribute:\n\n- **Give a Star:** The simplest way to show your support is to star the project on [GitHub](https://github.com/Artemonim/AgentDocstrings)! It increases the project's visibility.\n- **Support My Work:** Your financial contribution helps me dedicate more time to improving this tool and creating other open-source projects. On my [**Boosty page**](https://boosty.to/artemonim), you can:\n - Make a **one-time donation** to thank me for this specific project.\n - Become a **monthly supporter** to help all of my creative endeavors.\n- **Try a Recommended Tool:** This project was inspired by my work with LLMs. If you're looking for a great service to work with multiple neural networks, check out [**Syntx AI**](https://t.me/syntxaibot?start=aff_157453205). Using my referral link is another way to support my work at no extra cost to you.\n\nThank you for your support!\n\n## Contributing\n\nWe welcome contributions! Please see our [**Contribution Guide**](CONTRIBUTING.md) for detailed instructions on how to get started, our development workflow, and coding standards.\n\nIn short:\n\n1. Fork the repo and create your branch from `dev`.\n2. Add your feature or fix.\n3. Add/update tests.\n4. Update `CHANGELOG.md`.\n5. Submit a pull request to `dev`.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/Artemonim/agent-docstrings/issues)\n- **Documentation**: [GitHub README](https://github.com/Artemonim/agent-docstrings#readme)\n- **Source Code**: [GitHub Repository](https://github.com/Artemonim/agent-docstrings)\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Artemonim\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A command-line tool to auto-generate and update file-level docstrings summarizing classes and functions. Useful for maintaining a high-level overview of your files, especially in projects with code generated or modified by AI assistants.",
"version": "1.3.4",
"project_urls": {
"Changelog": "https://github.com/Artemonim/AgentDocstrings/blob/master/CHANGELOG.md",
"Documentation": "https://github.com/Artemonim/AgentDocstrings#readme",
"Homepage": "https://github.com/Artemonim/AgentDocstrings",
"Source": "https://github.com/Artemonim/AgentDocstrings",
"Tracker": "https://github.com/Artemonim/AgentDocstrings/issues"
},
"split_keywords": [
"docstrings",
" documentation",
" ai",
" developer-tools",
" automation",
" code-generator",
" maintainability",
" code-quality",
" static-analysis",
" pre-commit",
" linter",
" summarize-code",
" code-navigation",
" refactoring",
" python",
" java",
" kotlin",
" go",
" powershell",
" delphi",
" typescript",
" javascript",
" csharp",
" c++",
" c"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fd4895e83f8b46f95ee76b24ca7fe6317b0079995a4534bcef6a58a6203d2c8b",
"md5": "d978da14d7c78adf9cbca559f50a8562",
"sha256": "5558e7b5084993d318ea3255a4751a8794cbebf972e9aae34f9c04c5626377d5"
},
"downloads": -1,
"filename": "agent_docstrings-1.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d978da14d7c78adf9cbca559f50a8562",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 3828687,
"upload_time": "2025-07-08T09:48:04",
"upload_time_iso_8601": "2025-07-08T09:48:04.684515Z",
"url": "https://files.pythonhosted.org/packages/fd/48/95e83f8b46f95ee76b24ca7fe6317b0079995a4534bcef6a58a6203d2c8b/agent_docstrings-1.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cd02f614591ccdf0279f01f728e9622367d6aa3139b3caa431ca93ef9967c91d",
"md5": "9c1e1a62754f2c60455812d05ef19efd",
"sha256": "66f15157d93fed916fb97e391dfa0709adba0ced0956d5e9e57b73877a5fda2a"
},
"downloads": -1,
"filename": "agent_docstrings-1.3.4.tar.gz",
"has_sig": false,
"md5_digest": "9c1e1a62754f2c60455812d05ef19efd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 3831482,
"upload_time": "2025-07-08T09:48:06",
"upload_time_iso_8601": "2025-07-08T09:48:06.335275Z",
"url": "https://files.pythonhosted.org/packages/cd/02/f614591ccdf0279f01f728e9622367d6aa3139b3caa431ca93ef9967c91d/agent_docstrings-1.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 09:48:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Artemonim",
"github_project": "AgentDocstrings",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "agent-docstrings"
}
