DEV Community

Devadatta Baireddy
Devadatta Baireddy

Posted on

I Built a README Generator That Writes Better Docs Than Me

#python #devtools #opensource #automation

Every developer has written a README. And hated it.

You stare at a blank screen. "Do I put features first or installation?" You copy-paste the same sections from your last 10 projects. By the time you're done, you've wasted 30 minutes on what should take 5.

Last week, I got tired of this. So I built README Generator CLI — a tool that generates professional GitHub READMEs from a simple JSON config file. No more copy-paste. No more formatting debates.

Here's what happened: I ran it against 5 of my old projects. Every single one got better documentation automatically.

The Problem

Good documentation matters. GitHub's algorithm promotes repos with decent READMEs. Employers notice. Users trust projects that look professional.

But writing READMEs is boring and repetitive.

Every README has the same structure:

  • Description
  • Installation
  • Features
  • Usage examples
  • Contributing guidelines
  • License info

You write it the same way every time. Different projects, same tedious process.

The Solution

What if you just... described your project once, in JSON, and got a perfect README?

{
  "name": "My Awesome CLI",
  "description": "A fast JSON processor for DevOps",
  "installation": "pip install json-processor",
  "features": [
    "Parse nested JSON instantly",
    "Export to CSV/YAML",
    "Filter by multiple criteria"
  ],
  "examples": {
    "Basic": "json-processor data.json",
    "Advanced": "json-processor data.json --filter status=active"
  }
}
Enter fullscreen mode Exit fullscreen mode

Then run:

python readme_generator.py --config readme.json
Enter fullscreen mode Exit fullscreen mode

Done. Your README is generated with:

  • Proper Markdown formatting
  • Professional badges
  • All sections properly ordered
  • Install instructions
  • Usage examples
  • Support/donation links

Takes 10 seconds. Looks like 30 minutes of work.

What I Built

README Generator CLI is a single-file Python tool (no dependencies!) that:

✅ Reads JSON config — Define your project once

✅ Generates complete README — All standard sections included

✅ Validates before writing — Preview mode to check before committing

✅ Customizable — Add your own features, examples, dependencies

✅ Professional formatting — Badges, tables, proper Markdown structure

Feature Breakdown

  1. Automatic Structure — Headers, badges, sections all in the right order
  2. No Dependencies — Pure Python 3.8+, literally nothing else needed
  3. Validation Mode — Preview your README before generating the file
  4. Customizable Sections — Features, examples, dependencies, all optional
  5. Buy Me a Coffee Integration — Include your support link automatically

Real Example: Before vs After

Before (Manual) 

I'm going to write a README...
- What sections do I need?
- How should I format badges?
- Did I put examples in the right place?
- Is my installation section clear?
- Oh, I forgot to add a license section...
30 minutes later... GitHub repo with half-decent docs
Enter fullscreen mode Exit fullscreen mode

After (Using the Generator) 

{
  "name": "Email Validator CLI",
  "description": "Validate email addresses with syntax, disposable domain, and MX record checks",
  "features": [
    "Syntax validation",
    "Disposable domain detection",
    "MX record verification"
  ],
  "installation": "pip install email-validator-cli",
  "usage": "email-validator --help",
  "examples": {
    "Check single email": "email-validator user@example.com",
    "Validate from file": "email-validator --file emails.txt"
  }
}
Enter fullscreen mode Exit fullscreen mode 
python readme_generator.py --config readme.json
Enter fullscreen mode Exit fullscreen mode

Boom. Professional README in 5 seconds. Every time.

How It Works

The tool reads your JSON config and generates:

# Email Validator CLI

Validate email addresses with syntax, disposable domain, and MX record checks

✨ Features
- Syntax validation
- Disposable domain detection  
- MX record verification

## Installation
Enter fullscreen mode Exit fullscreen mode


bash
pip install email-validator-cli


## Usage
Enter fullscreen mode Exit fullscreen mode


bash
email-validator --help


## Examples

### Check single email
Enter fullscreen mode Exit fullscreen mode


bash
email-validator user@example.com


### Validate from file
Enter fullscreen mode Exit fullscreen mode


bash
email-validator --file emails.txt


[... and all other standard sections ...]
Enter fullscreen mode Exit fullscreen mode

Everything is automatic. You focus on the content (name, description, features) and the tool handles the presentation.

The Config Format

Super simple:

{
  "name": "Project Name",                    // Required
  "description": "What it does",             // Required
  "author": "Your Name",                     // Optional
  "license": "MIT",                          // Optional
  "repo_url": "https://github.com/...",      // Optional
  "buy_me_coffee": "https://buymeacoffee...", // Optional
  "installation": "pip install my-project",  // Optional
  "features": ["Feature 1", "Feature 2"],   // Optional
  "examples": {                              // Optional
    "Example Name": "command here"
  }
}
Enter fullscreen mode Exit fullscreen mode

Only name and description are required. Everything else is optional. The tool handles it.

Installation & Usage

Get It 

git clone https://github.com/godlmane/readme-generator-cli.git
cd readme-generator-cli
python readme_generator.py --help
Enter fullscreen mode Exit fullscreen mode

Or Just Use the Single File

Copy readme_generator.py into your project. That's it. No pip install needed.

Generate Your README 

# 1. Create readme.json with your project info
# 2. Run:
python readme_generator.py --config readme.json

# 3. Check your generated README.md
# 4. Commit it to GitHub
Enter fullscreen mode Exit fullscreen mode

Preview Before Committing 

python readme_generator.py --config readme.json --validate
Enter fullscreen mode Exit fullscreen mode

Shows you the README without writing it. Perfect for testing.

Real-World Use Cases

  1. Publish open source faster — Spend 5 minutes describing project, 5 seconds generating docs
  2. Bulk update READMEs — Got 10 projects? Generate all their READMEs in 1 minute
  3. Automate in CI/CD — Update docs automatically whenever your project changes
  4. Teach best practices — See what a professional README should look like
  5. Impress on GitHub — Well-documented projects get more stars, more users, more opportunities

The Time Savings

Let's do the math:

  • Manual README writing: 30 minutes per project
  • README Generator: 5 minutes (create config) + 5 seconds (run tool)
  • Savings per project: ~25 minutes
  • For 10 projects: 250 minutes = 4+ hours
  • For 50 projects: 1,250 minutes = 20+ hours saved

If you have multiple projects (and most of us do), this is a huge time saver.

What's Next

I'm working on:

  • Template options (minimal, extended, academic)
  • AI-powered feature suggestions
  • GitHub Actions integration
  • Multi-language support

Get It Now

👉 GitHub: readme-generator-cli

The tool is completely free and open source (MIT license).

Support My Work

If README Generator saved you time:

☕ Buy me a coffee — Help me build more tools like this

⭐ Star the repo on GitHub — Helps other developers find it

📢 Share this post — Help spread the word

Have you written a README today? Try the generator. Let me know what you think in the comments!

P.S. — Every tool I build is free. These tools are powered by readers like you. If you found this useful, your support means everything. ☕

Top comments (1)

Collapse
 
nyrok profile image
Hamza KONTE •

A README generator that actually understands the project structure rather than just templating is a great idea — good READMEs are genuinely hard to write because they require explaining things you've forgotten you know.

Curious how you handle the prompt for the "getting started" section — that's the part most READMEs get wrong (too terse, assumes too much). Do you give the LLM the actual project file tree + package.json and let it infer, or do you ask the user for context first?

This is close to what I've been working on with flompt (flompt.dev) — a visual prompt builder that structures prompts into semantic blocks (role, context, constraints, output format, examples, etc.) and compiles to Claude-optimized XML. For a README generator, the output_format block alone makes a huge difference — specifying exactly which sections you want and in what order prevents the LLM from improvising. Free and open-source, also works as MCP: claude mcp add flompt https://flompt.dev/mcp/

Is the generator web-based or a CLI tool?