253 lines
6.1 KiB
Markdown
253 lines
6.1 KiB
Markdown
# Auto README Generator CLI
|
|
|
|
[](https://pypi.org/project/auto-readme-cli/)
|
|
[](https://pypi.org/project/auto-readme-cli/)
|
|
[](https://opensource.org/licenses/MIT/)
|
|
|
|
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
|
|
|
|
```bash
|
|
pip install auto-readme-cli
|
|
```
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
auto-readme generate
|
|
```
|
|
|
|
### Generate with specific options
|
|
|
|
```bash
|
|
auto-readme generate --input /path/to/project --output README.md --template base
|
|
```
|
|
|
|
### Interactive Mode
|
|
|
|
```bash
|
|
auto-readme generate --interactive
|
|
```
|
|
|
|
### Preview README without writing
|
|
|
|
```bash
|
|
auto-readme preview
|
|
```
|
|
|
|
## Commands
|
|
|
|
### generate
|
|
|
|
Generate a README.md file for your project.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
auto-readme preview [OPTIONS]
|
|
```
|
|
|
|
### analyze
|
|
|
|
Analyze a project and display information.
|
|
|
|
```bash
|
|
auto-readme analyze [PATH]
|
|
```
|
|
|
|
### init-config
|
|
|
|
Generate a template configuration file.
|
|
|
|
```bash
|
|
auto-readme init-config --output .readmerc
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Configuration File (.readmerc)
|
|
|
|
Create a `.readmerc` file in your project root to customize README generation:
|
|
|
|
```yaml
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
auto-readme generate --template /path/to/custom_template.md.j2
|
|
```
|
|
|
|
## GitHub Actions Integration
|
|
|
|
Generate a GitHub Actions workflow to automatically update your README:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
git clone https://github.com/yourusername/auto-readme-cli.git
|
|
cd auto-readme-cli
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
pytest -xvs
|
|
```
|
|
|
|
### Code Formatting
|
|
|
|
```bash
|
|
black src/ tests/
|
|
isort src/ tests/
|
|
flake8 src/ tests/
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Changelog
|
|
|
|
See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
|
|
|
|
---
|
|
|
|
*Generated with ❤️ by Auto README Generator CLI*
|