# README Writer
## Project Overview and Description
**readme-writer** is an AI-powered tool designed to automate the generation of comprehensive README files for software projects. By leveraging the OpenAI API, it analyzes code files to produce detailed documentation that adheres to best practices. This tool is particularly beneficial for developers aiming to streamline their documentation process, ensuring clarity and accessibility for both beginners and experienced developers.
## Installation Instructions
### Basic Installation
To install the `readme-writer` package, ensure you have Python 3.8 or later, then use the following command:
```bash
pip install -e .
```
### Development Installation
For development purposes, including additional dependencies:
```bash
pip install -e ".[dev]"
```
### Alternative Installation
Clone the repository and install the required dependencies:
```bash
git clone https://github.com/yourusername/readme-writer.git
cd readme-writer
pip install -e .
```
## Usage Examples and API Documentation
The `readme-writer` provides a command-line interface (CLI) for generating README files.
### Basic CLI Usage
```bash
readme-writer /path/to/repository --api-key YOUR_OPENAI_API_KEY
```
### Python Module Usage
To generate documentation using Python:
```python
from readme_writer.file_processor import FileProcessor
from readme_writer.config import Config
from pathlib import Path
config = Config()
processor = FileProcessor(config)
repository_path = Path('/path/to/your/repository')
files = processor.discover_files(repository_path)
files_with_content = processor.read_all_files(files)
documentation = processor.format_files_for_documentation(files_with_content)
```
### OpenAI Client Example
```python
from readme_writer.openai_client import OpenAIClient
from readme_writer.config import Config
config = Config()
client = OpenAIClient(config)
content = "Your content here"
system_prompt = "Generate a README section"
documentation = client.generate_documentation(content, system_prompt)
```
### CLI Options
- `repository_path`: Path to the Git repository (required).
- `--model`, `-m`: OpenAI model to use (default: `gpt-4o`).
- `--output`, `-o`: Output file name (default: `README.md`).
- `--api-key`: OpenAI API key (or set `OPENAI_API_KEY` environment variable).
- `--temperature`, `-t`: OpenAI temperature (default: `0.3`).
- `--skip-files`: Additional file patterns to skip (comma-separated).
- `--max-tokens`: Maximum tokens per chunk (default: `6000`).
- `--no-diff`: Disable diff analysis for detecting changes.
## Diff Analysis Feature
The `readme-writer` now includes intelligent diff analysis that detects changes between repository updates. This feature helps maintain accurate documentation by:
### What it detects:
- **Added files**: New files that should be documented
- **Deleted files**: Files that should be removed from documentation
- **Modified files**: Files that may need updated documentation
### How it works:
1. **Snapshot Creation**: When you run the tool, it creates a snapshot of the current repository state
2. **Change Detection**: On subsequent runs, it compares the current state with the previous snapshot
3. **Smart Updates**: The AI uses this change information to make targeted updates to your README
### Benefits:
- **Accurate Documentation**: Removes references to deleted files and adds documentation for new files
- **Efficient Updates**: Only updates sections that need changes, preserving existing content
- **Change Tracking**: Provides detailed information about what changed since the last update
### Usage:
```bash
# Normal usage with diff analysis (default)
readme-writer /path/to/repository
# Disable diff analysis if needed
readme-writer /path/to/repository --no-diff
```
### Snapshot Storage:
- Snapshots are stored in `.readme-writer-snapshots/` directory
- Each repository gets its own snapshot file
- Snapshots are automatically managed and updated
## Configuration Options and Environment Variables
The `readme-writer` can be configured using both CLI options and environment variables. Key configurations include:
- **Model Selection**: Choose the OpenAI model via the `--model` option or `OPENAI_MODEL` environment variable.
- **Output File**: Specify the output file with `--output` or `OUTPUT_FILE`.
- **API Key**: Set the OpenAI API key using `--api-key` or `OPENAI_API_KEY`.
- **Temperature**: Adjust the creativity of the AI with `--temperature`.
### Environment Variables
- `OPENAI_API_KEY`: API key for OpenAI services.
- `OPENAI_MODEL`: Default OpenAI model to use.
- `OUTPUT_FILE`: Default output file name.
- `VERSION`: Package version.
## Dependencies and Requirements
The project requires Python 3.8 or higher. Key dependencies include:
- `openai>=1.0.0`
- `click>=8.0.0`
- `tiktoken>=0.5.0`
- `rich>=13.0.0`
- `pyyaml>=6.0`
- `jinja2>=3.0.0`
## Contributing Guidelines
We welcome contributions to the `readme-writer` project. To contribute:
1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Ensure code quality with `black`, `flake8`, and `mypy`.
4. Write tests for your changes and ensure all tests pass.
5. Submit a pull request with a detailed description of your changes.
## GitHub Actions and PyPI Publishing
This project includes GitHub Actions workflows for automated testing and publishing to PyPI.
### Available Workflows
1. **Publish to PyPI** (`.github/workflows/publish.yml`):
- Simple workflow for publishing to PyPI
- Triggers on releases or manual dispatch
### Setting up PyPI Publishing
To enable automatic publishing to PyPI, you need to set up the following GitHub secret:
1. **PYPI_API_TOKEN**: Your PyPI API token
- Go to [PyPI Account Settings](https://pypi.org/manage/account/)
- Create an API token with "Entire account" scope
- Add it as a repository secret named `PYPI_API_TOKEN`
### Publishing Methods
#### Method 1: GitHub Release
1. Create a new release on GitHub
2. Tag it with the version (e.g., `v1.0.1`)
3. The workflow will automatically publish to PyPI
#### Method 2: Manual Dispatch
1. Go to Actions tab in your repository
2. Select "Publish to PyPI"
3. Click "Run workflow"
4. Enter the version number (e.g., `1.0.1`)
5. Click "Run workflow"
### Version Management
The workflow automatically updates the version in `pyproject.toml` when publishing. Make sure to:
- Update the version in `pyproject.toml` before creating a release
- Use semantic versioning (e.g., `1.0.0`, `1.0.1`, `1.1.0`)
## Makefile Targets
The Makefile includes several useful commands:
- `install`: Install the package in development mode.
- `clean`: Clean build artifacts and cache.
- `build`: Build the package.
- `publish`: Build and publish to PyPI (requires proper configuration).
- `check-package`: Check the built package for issues.
## Important Notes and Considerations
- Ensure the OpenAI API key is set either via the environment variable or the CLI option to avoid errors during execution.
- The tool is in beta; expect potential changes and improvements.
- Proper configuration of the environment and dependencies is crucial for optimal performance.
- Monitor your API usage to manage expenses, as the tool estimates costs based on token usage.
For more detailed information, please refer to the individual file documentation and comments within the code.
Raw data
{
"_id": null,
"home_page": null,
"name": "readme-writer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "documentation, readme, ai, openai, git",
"author": "Readme generator",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4c/63/1bc9b8af60bc519f2e154069154fff49cf0e3f1e296ad537eccb939bbe34/readme_writer-1.0.5.tar.gz",
"platform": null,
"description": "# README Writer\n\n## Project Overview and Description\n\n**readme-writer** is an AI-powered tool designed to automate the generation of comprehensive README files for software projects. By leveraging the OpenAI API, it analyzes code files to produce detailed documentation that adheres to best practices. This tool is particularly beneficial for developers aiming to streamline their documentation process, ensuring clarity and accessibility for both beginners and experienced developers.\n\n## Installation Instructions\n\n### Basic Installation\n\nTo install the `readme-writer` package, ensure you have Python 3.8 or later, then use the following command:\n\n```bash\npip install -e .\n```\n\n### Development Installation\n\nFor development purposes, including additional dependencies:\n\n```bash\npip install -e \".[dev]\"\n```\n\n### Alternative Installation\n\nClone the repository and install the required dependencies:\n\n```bash\ngit clone https://github.com/yourusername/readme-writer.git\ncd readme-writer\npip install -e .\n```\n\n## Usage Examples and API Documentation\n\nThe `readme-writer` provides a command-line interface (CLI) for generating README files.\n\n### Basic CLI Usage\n\n```bash\nreadme-writer /path/to/repository --api-key YOUR_OPENAI_API_KEY\n```\n\n### Python Module Usage\n\nTo generate documentation using Python:\n\n```python\nfrom readme_writer.file_processor import FileProcessor\nfrom readme_writer.config import Config\nfrom pathlib import Path\n\nconfig = Config()\nprocessor = FileProcessor(config)\nrepository_path = Path('/path/to/your/repository')\n\nfiles = processor.discover_files(repository_path)\nfiles_with_content = processor.read_all_files(files)\ndocumentation = processor.format_files_for_documentation(files_with_content)\n```\n\n### OpenAI Client Example\n\n```python\nfrom readme_writer.openai_client import OpenAIClient\nfrom readme_writer.config import Config\n\nconfig = Config()\nclient = OpenAIClient(config)\n\ncontent = \"Your content here\"\nsystem_prompt = \"Generate a README section\"\ndocumentation = client.generate_documentation(content, system_prompt)\n```\n\n### CLI Options\n\n- `repository_path`: Path to the Git repository (required).\n- `--model`, `-m`: OpenAI model to use (default: `gpt-4o`).\n- `--output`, `-o`: Output file name (default: `README.md`).\n- `--api-key`: OpenAI API key (or set `OPENAI_API_KEY` environment variable).\n- `--temperature`, `-t`: OpenAI temperature (default: `0.3`).\n- `--skip-files`: Additional file patterns to skip (comma-separated).\n- `--max-tokens`: Maximum tokens per chunk (default: `6000`).\n- `--no-diff`: Disable diff analysis for detecting changes.\n\n## Diff Analysis Feature\n\nThe `readme-writer` now includes intelligent diff analysis that detects changes between repository updates. This feature helps maintain accurate documentation by:\n\n### What it detects:\n- **Added files**: New files that should be documented\n- **Deleted files**: Files that should be removed from documentation\n- **Modified files**: Files that may need updated documentation\n\n### How it works:\n1. **Snapshot Creation**: When you run the tool, it creates a snapshot of the current repository state\n2. **Change Detection**: On subsequent runs, it compares the current state with the previous snapshot\n3. **Smart Updates**: The AI uses this change information to make targeted updates to your README\n\n### Benefits:\n- **Accurate Documentation**: Removes references to deleted files and adds documentation for new files\n- **Efficient Updates**: Only updates sections that need changes, preserving existing content\n- **Change Tracking**: Provides detailed information about what changed since the last update\n\n### Usage:\n```bash\n# Normal usage with diff analysis (default)\nreadme-writer /path/to/repository\n\n# Disable diff analysis if needed\nreadme-writer /path/to/repository --no-diff\n```\n\n### Snapshot Storage:\n- Snapshots are stored in `.readme-writer-snapshots/` directory\n- Each repository gets its own snapshot file\n- Snapshots are automatically managed and updated\n\n## Configuration Options and Environment Variables\n\nThe `readme-writer` can be configured using both CLI options and environment variables. Key configurations include:\n\n- **Model Selection**: Choose the OpenAI model via the `--model` option or `OPENAI_MODEL` environment variable.\n- **Output File**: Specify the output file with `--output` or `OUTPUT_FILE`.\n- **API Key**: Set the OpenAI API key using `--api-key` or `OPENAI_API_KEY`.\n- **Temperature**: Adjust the creativity of the AI with `--temperature`.\n\n### Environment Variables\n\n- `OPENAI_API_KEY`: API key for OpenAI services.\n- `OPENAI_MODEL`: Default OpenAI model to use.\n- `OUTPUT_FILE`: Default output file name.\n- `VERSION`: Package version.\n\n## Dependencies and Requirements\n\nThe project requires Python 3.8 or higher. Key dependencies include:\n\n- `openai>=1.0.0`\n- `click>=8.0.0`\n- `tiktoken>=0.5.0`\n- `rich>=13.0.0`\n- `pyyaml>=6.0`\n- `jinja2>=3.0.0`\n\n## Contributing Guidelines\n\nWe welcome contributions to the `readme-writer` project. To contribute:\n\n1. Fork the repository.\n2. Create a new branch for your feature or bugfix.\n3. Ensure code quality with `black`, `flake8`, and `mypy`.\n4. Write tests for your changes and ensure all tests pass.\n5. Submit a pull request with a detailed description of your changes.\n\n## GitHub Actions and PyPI Publishing\n\nThis project includes GitHub Actions workflows for automated testing and publishing to PyPI.\n\n### Available Workflows\n\n1. **Publish to PyPI** (`.github/workflows/publish.yml`):\n - Simple workflow for publishing to PyPI\n - Triggers on releases or manual dispatch\n\n### Setting up PyPI Publishing\n\nTo enable automatic publishing to PyPI, you need to set up the following GitHub secret:\n\n1. **PYPI_API_TOKEN**: Your PyPI API token\n - Go to [PyPI Account Settings](https://pypi.org/manage/account/)\n - Create an API token with \"Entire account\" scope\n - Add it as a repository secret named `PYPI_API_TOKEN`\n\n### Publishing Methods\n\n#### Method 1: GitHub Release\n1. Create a new release on GitHub\n2. Tag it with the version (e.g., `v1.0.1`)\n3. The workflow will automatically publish to PyPI\n\n#### Method 2: Manual Dispatch\n1. Go to Actions tab in your repository\n2. Select \"Publish to PyPI\"\n3. Click \"Run workflow\"\n4. Enter the version number (e.g., `1.0.1`)\n5. Click \"Run workflow\"\n\n### Version Management\n\nThe workflow automatically updates the version in `pyproject.toml` when publishing. Make sure to:\n- Update the version in `pyproject.toml` before creating a release\n- Use semantic versioning (e.g., `1.0.0`, `1.0.1`, `1.1.0`)\n\n## Makefile Targets\n\nThe Makefile includes several useful commands:\n\n- `install`: Install the package in development mode.\n- `clean`: Clean build artifacts and cache.\n- `build`: Build the package.\n- `publish`: Build and publish to PyPI (requires proper configuration).\n- `check-package`: Check the built package for issues.\n\n## Important Notes and Considerations\n\n- Ensure the OpenAI API key is set either via the environment variable or the CLI option to avoid errors during execution.\n- The tool is in beta; expect potential changes and improvements.\n- Proper configuration of the environment and dependencies is crucial for optimal performance.\n- Monitor your API usage to manage expenses, as the tool estimates costs based on token usage.\n\nFor more detailed information, please refer to the individual file documentation and comments within the code.\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered documentation generator for Git repositories using OpenAI API",
"version": "1.0.5",
"project_urls": null,
"split_keywords": [
"documentation",
" readme",
" ai",
" openai",
" git"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "75c4be8f308f9ca76b020eff0b4aef478b7b463278f4c510a5756e49be3b348b",
"md5": "3d058e031cbd1ed6b9d22fb6cddfc24d",
"sha256": "2a23daea994f2cdfca7b4f321fe9dae72c3b6f5b9a2dbc2b3cb48b45c5c52d90"
},
"downloads": -1,
"filename": "readme_writer-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d058e031cbd1ed6b9d22fb6cddfc24d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18020,
"upload_time": "2025-07-22T13:46:30",
"upload_time_iso_8601": "2025-07-22T13:46:30.675202Z",
"url": "https://files.pythonhosted.org/packages/75/c4/be8f308f9ca76b020eff0b4aef478b7b463278f4c510a5756e49be3b348b/readme_writer-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4c631bc9b8af60bc519f2e154069154fff49cf0e3f1e296ad537eccb939bbe34",
"md5": "fc94ab2243a72a3559218823fea870a4",
"sha256": "aa743ec0269a95e97c0e1cc7e41148bb8fd13d5312854d629e0b42bd5ef281d0"
},
"downloads": -1,
"filename": "readme_writer-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "fc94ab2243a72a3559218823fea870a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16978,
"upload_time": "2025-07-22T13:46:31",
"upload_time_iso_8601": "2025-07-22T13:46:31.683301Z",
"url": "https://files.pythonhosted.org/packages/4c/63/1bc9b8af60bc519f2e154069154fff49cf0e3f1e296ad537eccb939bbe34/readme_writer-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 13:46:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "readme-writer"
}
JSON