Metadata-Version: 2.4
Name: docstring_generator_ext
Version: 1.0.2
Summary: Generate Docstrings with type-hint information.
Author-email: FelixTheC <fberndt87@gmail.com>
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: pybind11>=3.0.4

# Docstring Generator Extension

[![C++ Tests](https://github.com/FelixTheC/docstring_generator_ext/actions/workflows/cpp-tests.yml/badge.svg)](https://github.com/FelixTheC/docstring_generator_ext/actions/workflows/cpp-tests.yml)
[![Build Extension](https://github.com/FelixTheC/docstring_generator_ext/actions/workflows/check-build-ext.yml/badge.svg)](https://github.com/FelixTheC/docstring_generator_ext/actions/workflows/check-build-ext.yml)
[![PyPI version](https://img.shields.io/pypi/v/docstring_generator_ext.svg)](https://pypi.org/project/docstring_generator_ext/)
[![Python versions](https://img.shields.io/pypi/pyversions/docstring_generator_ext.svg)](https://pypi.org/project/docstring_generator_ext/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`docstring_generator_ext` is a high-performance Python extension written in C++ (using pybind11) designed to automatically generate and inject docstrings into Python source files. It leverages Python's `ast` module to extract type-hint information and function signatures to create well-formatted docstrings in various styles.

## Features

- **Automatic Docstring Injection**: Parses Python files and inserts docstrings for functions and methods.
- **Type-Hint Awareness**: Extracts type information from annotations and default values.
- **Multiple Styles**: Supports popular docstring formats:
  - **reST** (reStructuredText)
  - **Google** style
  - **NumPy** style
- **High Performance**: Core logic implemented in C++ for fast processing.
- **Preserves Existing Content**: Can update existing docstrings while trying to preserve manually added descriptions (using a special `$` marker convention).

## Installation

### Prerequisites

- Python 3.13 or higher
- A C++ compiler with C++20 support (e.g., GCC, Clang, or MSVC)
- `pybind11`

### Building from Source

1. Clone the repository:
   ```bash
   git clone https://github.com/FelixTheC/docstring_generator_ext.git
   cd docstring_generator_ext
   ```

2. Install the `build` package:
   ```bash
   pip install build
   ```

3. Build the package:
   ```bash
   python -m build
   ```

4. Install the built wheel:
   ```bash
   pip install dist/docstring_generator_ext-*.whl
   ```

## Usage

After installation, you can use the extension in your Python scripts:

```python
import docstring_generator_ext

# Path to the Python file you want to process
file_path = "path/to/your_script.py"

# Choose a style: GOOGLE, NUMPY, or reST
style = docstring_generator_ext.DocstringFormatStyle.GOOGLE

# Generate and inject docstrings
docstring_generator_ext.parse_file(file_path, style)
```

### Docstring Styles

The extension provides an enum `DocstringFormatStyle` to choose the desired output:

- `docstring_generator_ext.DocstringFormatStyle.reST`
- `docstring_generator_ext.DocstringFormatStyle.GOOGLE`
- `docstring_generator_ext.DocstringFormatStyle.NUMPY`

## Authors

- **FelixTheC**

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

