README files are usually the last thing I write.
Not because they’re unimportant — but because by the time the code works, I just want to ship. Over time I noticed the same pattern: inconsistent sections, missing install steps, or a README that didn’t reflect the project at all.
I didn’t want a smarter template. I wanted less friction.
So I built a small Python CLI that generates a clean, GitHub-ready README with almost no setup.
Design goal: zero configuration
The main constraint I set for myself was:
A developer should be able to try it in under 60 seconds.
That ruled out:
• Config files
• Manual template selection
• Long command flags
If that felt slow or confusing, the tool had failed its goal.
Implementation decisions
- Typer for CLI ergonomics
I chose Typer because:
• Type hints double as CLI definitions
• Commands stay readable as the tool grows
• Help output is clean by default
This helped keep the surface area small while still being extensible.
⸻
- Jinja2 templates (tested) Templates are easy to add — but easy to break.
Instead of treating them as static files, I:
• Versioned templates
• Added tests to validate output structure
• Enforced required sections per template
This avoids generating a README that looks polished but misses critical sections.
⸻
-
Smart defaults over questions. Rather than asking everything, the tool:
• Infers project name from the directory
• Suggests sections automatically
• Only prompts when needed
Fewer prompts = faster flow.
⸻
-
Rich for feedback, not decoration I used Rich sparingly:
• Clear success/failure messages
• Human-readable errors
• No unnecessary animations
CLI tools should feel calm, not flashy. But also not boring.
⸻
What I learned shipping my first PyPI package
One thing I didn’t expect was how different “working locally” is from “working once published.”
In my first release, readmegen init ran — but didn’t actually generate a README.
The issue wasn’t the logic. It was packaging.
I hadn’t bundled my Jinja2 templates in the PyPI distribution, so once installed, the CLI couldn’t find them.
That forced me to learn:
• How Python packaging actually works
• Why MANIFEST.in matters
• How to include non-code files in a distribution
• Semantic versioning and republishing fixes properly
It was frustrating — but also satisfying. Shipping something people can install teaches lessons you don’t get from local scripts.
⸻
What I deliberately didn’t add (yet)
There’s currently a placeholder for AI enhancement.
I could auto-generate descriptions, features, or usage sections — but I’m cautious. Bad AI-generated docs can be worse than no docs at all.
Before adding it, I wanted to understand how developers actually feel about it.
⸻
Where this could go next
Some ideas I’m considering:
• AI-assisted rewriting (opt-in)
• Project structure analysis for smarter sections
• README linting / suggestions instead of generation
But I’m trying to keep the core simple.
Try it (if you want)
pip install readmegen-oss
readmegen init
Repo + docs are here: https://github.com/josiah-mbao/ReadmeGen
Live site: https://josiah-mbao.github.io/readmegen-site/
Question for you
Would you ever let AI write your README files?
I'm genuinely curious before pushing this further.
Top comments (0)