Metadata-Version: 2.4
Name: readme-auto-generator
Version: 2.0.0
Summary: CLI tool that scaffolds README.md from project layout and manifest files (offline, no API)
Author: Saanika Patil
License-Expression: MIT
Keywords: readme,documentation,cli,code-analysis,static,markdown
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# README Auto-Generator

![Python](https://img.shields.io/badge/python-3.9+-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Offline](https://img.shields.io/badge/API-none-success)

Point it at any codebase. Get a structured `README.md` from layout and manifest files — **no API keys**, no network calls.

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [How It Works](#how-it-works)
- [Contributing](#contributing)
- [License](#license)

---

## Overview

README Auto-Generator is a CLI tool that scans a local project directory, collects manifest files (for example `package.json`, `pyproject.toml`, `requirements.txt`), builds a directory tree, detects languages from extensions, and **assembles a README template** you can refine. It does not call external AI services.

See [`PROJECT.md`](PROJECT.md) for the full project document, design decisions, and learning goals.

---

## Features

- Works offline — standard library only at runtime
- Scans common stacks: Python, JavaScript/TypeScript, Node, Rust, Go, and more (via extensions and manifests)
- Reads high-value manifests automatically (`package.json`, `requirements.txt`, `Dockerfile`, `Makefile`, etc.)
- Builds a directory tree and samples entry-point source files (size-capped)
- Respects ignore rules: skips `node_modules`, `__pycache__`, `.git`, binaries, and images
- Dry-run mode to preview output without writing to disk

---

## Tech Stack

| Component | Technology        |
|-----------|-------------------|
| Language  | Python 3.9+       |
| CLI       | `argparse` (stdlib) |
| File I/O  | `pathlib` (stdlib) |

---

## Project Structure

```
readme-auto-generator/
├── main.py                    Legacy entry point (if present)
├── requirements.txt           Documents stdlib-only runtime
├── setup.py
├── pyproject.toml
├── .gitignore
├── PROJECT.md                 Full project document
├── README.md                  This file
├── readme_generator/
│   ├── __init__.py
│   ├── analyzer.py            Codebase scanner
│   ├── generator.py           README assembly from context
│   └── cli.py                 Command-line interface
└── examples/
    └── sample_output.md       Example generated README
```

---

## Prerequisites

- Python 3.9 or higher

---

## Installation

```bash
# 1. Clone the repo
git clone https://github.com/yourname/readme-auto-generator.git
cd readme-auto-generator

# 2. Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

# 3. Install as a CLI tool
pip install -e .
```

---

## Configuration

No API keys or environment variables are required. Optional templates like `.env.example` are detected for the generated **Configuration** section when present in the project you scan.

---

## Usage

Install exposes the `readme-gen` command ([console script](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#console-scripts)).

### Basic — generate README for a project

```bash
readme-gen /path/to/your/project
```

This writes `README.md` into the target project directory (unless it exists — you will be prompted).

### Specify a custom output path

```bash
readme-gen /path/to/your/project --output /path/to/custom/README.md
```

### Preview without writing to disk

```bash
readme-gen /path/to/your/project --dry-run
```

### Overwrite an existing README without prompting

```bash
readme-gen /path/to/your/project --overwrite
```

### Run as a module

```bash
python -m readme_generator /path/to/your/project --help
```

### Options

```
usage: readme-gen [-h] [--output OUTPUT] [--overwrite] [--dry-run] [--version]
                  project_path
```

---

## How It Works

1. **Analyze** — `analyzer.py` walks the project directory, builds a directory tree, reads manifest files and key source files, and detects languages from file extensions.

2. **Generate** — `generator.py` derives title, description, install hints, and tables from that context and emits Markdown sections (overview, tech stack, structure, usage stubs, manifest excerpts).

3. **Output** — The CLI writes the Markdown to disk or prints it when `--dry-run` is set.

---

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -m 'Add my feature'`
4. Push: `git push origin feature/my-feature`
5. Open a Pull Request

---

## License

MIT License. See [LICENSE](LICENSE) for details.
