readme-writer 1.0.2

AI-powered documentation generator for Git repositories using OpenAI API

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:

pip install -e .

Development Installation

For development purposes, including additional dependencies:

pip install -e ".[dev]"

Alternative Installation

Clone the repository and install the required dependencies:

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

readme-writer /path/to/repository --api-key YOUR_OPENAI_API_KEY

Python Module Usage

To generate documentation using 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

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).

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
   • 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.