readme-auto-generator 2.0.0

CLI tool that scaffolds README.md from project layout and manifest files (offline, no API)

README Auto-Generator

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
• Features
• Tech Stack
• Project Structure
• Prerequisites
• Installation
• Configuration
• Usage
• How It Works
• Contributing
• 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 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

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

Basic — generate README for a project

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

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

Preview without writing to disk

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

Overwrite an existing README without prompting

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

Run as a module

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 for details.