A powerful CLI tool that automatically generates comprehensive README.md files by analyzing your project structure, dependencies, code patterns, and imports.

Features

Automatic Project Analysis: Scans directory structure to identify files, folders, and patterns
Multi-Language Support: Supports Python, JavaScript, Go, and Rust projects
Dependency Detection: Parses requirements.txt, package.json, go.mod, and Cargo.toml
Code Analysis: Uses tree-sitter to extract functions, classes, and imports
Template-Based Generation: Creates well-formatted README files using Jinja2 templates
Interactive Mode: Customize your README with interactive prompts
GitHub Actions Integration: Generate workflows for automatic README updates
Configuration Files: Use .readmerc files to customize generation behavior

Installation

From PyPI

pip install auto-readme-cli

From Source

git clone https://github.com/yourusername/auto-readme-cli.git
cd auto-readme-cli
pip install -e .

Quick Start

Generate a README for your project

auto-readme generate

Generate with specific options

auto-readme generate --input /path/to/project --output README.md --template base

Interactive Mode

auto-readme generate --interactive

Preview README without writing

auto-readme preview

Commands

generate

Generate a README.md file for your project.

auto-readme generate [OPTIONS]

Options:

Option	Description
`-i, --input DIRECTORY`	Input directory to analyze (default: current directory)
`-o, --output FILE`	Output file path (default: README.md)
`-I, --interactive`	Run in interactive mode
`-t, --template TEMPLATE`	Template to use (base, minimal, detailed)
`-c, --config FILE`	Path to configuration file
`--github-actions`	Generate GitHub Actions workflow
`-f, --force`	Force overwrite existing README
`--dry-run`	Preview without writing file

preview

Preview the generated README without writing to file.

auto-readme preview [OPTIONS]

analyze

Analyze a project and display information.

auto-readme analyze [PATH]

init-config

Generate a template configuration file.

auto-readme init-config --output .readmerc

Configuration

Configuration File (.readmerc)

Create a .readmerc file in your project root to customize README generation:

project_name: "My Project"
description: "A brief description of your project"
template: "base"
interactive: false

sections:
  order:
    - title
    - description
    - overview
    - installation
    - usage
    - features
    - api
    - contributing
    - license

custom_fields:
  author: "Your Name"
  email: "your.email@example.com"

pyproject.toml Configuration

You can also configure auto-readme in your pyproject.toml:

[tool.auto-readme]
filename = "README.md"
sections = ["title", "description", "installation", "usage", "api"]

Supported Languages

Language	Markers	Dependency Files
Python	pyproject.toml, setup.py, requirements.txt	requirements.txt, pyproject.toml
JavaScript	package.json	package.json
TypeScript	package.json, tsconfig.json	package.json
Go	go.mod	go.mod
Rust	Cargo.toml	Cargo.toml

Template System

The tool uses Jinja2 templates for README generation. Built-in templates:

base: Standard README with all sections
minimal: Basic README with essential information
detailed: Comprehensive README with extensive documentation

Custom Templates

You can create custom templates by placing .md.j2 files in a templates directory and specifying the path:

auto-readme generate --template /path/to/custom_template.md.j2

GitHub Actions Integration

Generate a GitHub Actions workflow to automatically update your README:

auto-readme generate --github-actions

This creates .github/workflows/readme-update.yml that runs on:

Push to main/master branch
Changes to source files
Manual workflow dispatch

Project Structure

auto-readme-cli/
├── src/
│   └── auto_readme/
│       ├── __init__.py
│       ├── cli.py              # Main CLI interface
│       ├── models/              # Data models
│       ├── parsers/             # Dependency parsers
│       ├── analyzers/           # Code analyzers
│       ├── templates/           # Jinja2 templates
│       ├── utils/               # Utility functions
│       ├── config/              # Configuration handling
│       ├── interactive/         # Interactive wizard
│       └── github/              # GitHub Actions integration
├── tests/                       # Test suite
├── pyproject.toml
└── README.md

Development

Setting up Development Environment

git clone https://github.com/yourusername/auto-readme-cli.git
cd auto-readme-cli
pip install -e ".[dev]"

Running Tests

pytest -xvs

Code Formatting

black src/ tests/
isort src/ tests/
flake8 src/ tests/

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes.

Generated with ❤️ by Auto README Generator CLI