DEV Community

Cover image for 🤖 Teaching the Cyborg to Document: Auto-Generated README.md’s with Style
raymonepping
raymonepping

Posted on

🤖 Teaching the Cyborg to Document: Auto-Generated README.md’s with Style

#devops #documentation #automation #bash

🧠 Why I Built This

Let’s be honest: Documentation is usually an afterthought.
We ship the CLI, tag the release, maybe slap a README together — and then… forget about it.

But for a growing suite of modular, Homebrew-packaged Bash CLIs (like folder_tree, repository_backup, radar_love…), that pattern falls apart fast. Outdated docs? Broken install steps? Yuck.

I wanted:

  • Docs that feel personal and consistent
  • Documentation that stays up-to-date by default
  • The ability to inject quotes, visuals, and folder trees — without manual edits
  • To make the docs look good, because… tools that look good get used!

So I built: self_doc.sh.

TL;DR:
I automated my CLI documentation with Bash and modular templates, so every release ships with an up-to-date, beautiful README.md. Here’s how.

🛠️ What Does self_doc.sh Do?

Auto-detects your CLI’s binary, version, and metadata

Loads optional CLI-specific .cli.vars for easy customization

Uses modular Markdown templates (like readme_header.tpl, readme_quote.tpl, etc.)

Generates a clean, attractive README.md file — ready to commit or publish

Falls back gracefully if visual tools like folder_tree aren’t installed

Injects warnings and install hints automatically

Runs anywhere: No dependencies outside Bash + coreutils

It’s like a little CI pipeline for your docs — but it’s fast, local, and always in sync.

📦 Template-Driven Docs

Instead of one big heredoc, self_doc.sh leverages a folder of template snippets:

tpl/
├── readme_01_header.tpl
├── readme_02_project.tpl
├── readme_03_structure.tpl
├── readme_04_body.tpl
├── readme_05_quote.tpl
├── readme_06_article.tpl
└── readme_07_footer.tpl
Enter fullscreen mode Exit fullscreen mode

Templates use smart placeholders:

{{CLI_NAME}}

{{VERSION}}

{{TAGLINE}}

{{FOLDER_TREE}} ← replaced by a live tree view

Just reorder, remix, or reuse template files across projects. Zero lock-in.

🌳 Smart Fallbacks: folder_tree vs. tree

If you have the folder_tree CLI installed, the README gets emoji-rich, beautiful output.
No folder_tree? It falls back to tree.

No tree either? You get this in your docs:

❌ No tree tool available! Install either folder_tree or tree for full functionality.

No conditionals needed in your templates. No manual fixes. It Just Works™.

✨ Features at a Glance

  • ✅ Full CLI arg parsing (long + short flags)
  • 🧠 Auto-discovers CLI binary + version
  • 🧱 Modular template support (with fallback)
  • 💬 Helpful errors if a template file is missing
  • 📁 Dynamic folder structure rendering
  • 🚫 Dry-run and quiet modes for scripting/CI
  • 🍺 Homebrew-link and quote injection via .cli.vars
  • 🧽 Cleans emoji/ANSI codes from folder trees
  • 🔧 One-liner install suggestions if missing dependencies

📄 Example Output

Here’s a real snippet from an auto-generated README:

🌳 folder_tree  
CLI tool that visualizes and documents folder structures

Version: 1.0.5

> ⚠️ folder_tree CLI not found. This structure was generated using standard `tree` as fallback.
> To install folder_tree: `brew install raymonepping/folder-tree-cli/folder-tree-cli`

./
├── bin/
│   └── folder_tree
├── lib/
│   ├── folder_tree_utils.sh
│   └── self_doc.sh
└── tpl/
    └── readme_*.tpl
Enter fullscreen mode Exit fullscreen mode

You get context, usage, and install hints — all without hand-writing Markdown.

🔍 Where I Use It

This one script now powers the docs for:

  • folder_tree — structure-aware CLI
  • radar_love — secret leak simulation for Vault Radar
  • repository_audit — audit all the Git repos in your folders
  • repository_backup — safe, modular, Homebrew-ready backup CLI

They all document themselves.
One command. No drift.

📈 Zero-Drift Docs — For Real

Once installed (Homebrew or manual), just point self_doc at your project. Examples:

# In a project folder with ./bin/my_cli:
self_doc

# To use templates from another repo:
self_doc -t ./x/tpl -f ./x/bin/y
Enter fullscreen mode Exit fullscreen mode

No guessing. No copying output.
Just a live README that always matches your code.

🧪 Real-World Value

This is more than just pretty READMEs:

  • Keeps your repos hygienic (especially when you have dozens)
  • Makes it easy for others to fork/contribute
  • Onboarding? Instant context.
  • Reinforces a culture of automation — even for docs

🧰 Get Started!

Want to automate docs for your own Bash CLI project?
Clone it the old-school way:

curl -O https://raw.githubusercontent.com/raymonepping/folder_tree_cli/main/lib/self_doc.sh
chmod +x self_doc.sh
./self_doc.sh --tpl-dir ./tpl --outfile README.md
Enter fullscreen mode Exit fullscreen mode

Or, the Homebrew way (for easy updates):

brew install raymonepping/self-doc-gen-cli/self-doc-gen-cli
brew upgrade self-doc-gen-cli    # To update later
self_doc --help
Enter fullscreen mode Exit fullscreen mode

Homebrew keeps you up to date, everywhere.

🔚 Final Thoughts

Docs don’t have to be dull. Or manual. Or outdated.
With the right automation, they’re a first-class citizen of your CLI — a mirror of your code.

self_doc.sh isn’t just a helper script. It’s your CLI’s reflection.

So…

Build your CLIs. Let them document themselves.

It’s Bash, top to bottom. No YAML hell. No Node/Go runtimes.
Just you, your logic, and docs that never drift.

📦 Grab the Script + Templates

Check it out on GitHub:
👉 https://github.com/raymonepping/folder_tree_cli/tree/main/lib/self_doc.sh

Or just grab the raw script:
👉 https://raw.githubusercontent.com/raymonepping/folder_tree_cli/main/lib/self_doc.sh

Feel free to adapt for your own projects!
Questions or feedback? Drop a comment below 👇

Top comments (0)