AWS Builder Center

Builder Center

README Read better: Automating Repo Summaries with Amazon Q Developer

README Read better: Automating Repo Summaries with Amazon Q Developer

An app to summarize the details of the workflow and commits of a public GitHub repository

Amudha Balamurugan

Cloud Data Engineer
Learning through practical application is currently my preferred approach for acquiring new technological skills. GitHub hosts a significant number of repositories to explore, spanning from basic to complex projects. Some are accompanied by a straightforward methodology and comprehensive documentation in the README, although this is not universally the case.
I always dedicate additional time to comprehending the procedures employed during the review of their projects. There is a significant need for concise documentation within project repositories to enhance efficiency. Accordingly, I am here to introduce my automatic document generator, which can scan any public GitHub repository and produce a summary of its contents within seconds.

How does it work?

Project File Structure

1
2
3
4
5
6
7
q-docgen/
├── scripts/
│ └── generate-summary.js # Main script using Q CLI
├── generated/
│ └── PROJECT_SUMMARY.md # Output goes here
├── package.json # Includes npm scripts
└── README.md # Project readme Project Structure

npm Script

You can generate documentation using a simple command:
npm run docgen -- https://github.com/GitHub-Username/repo-name

How Amazon Q CLI Is Used

We employ the q chat command programmatically via Node.js to input structured repository data and procure a natural language project summary.
An example prompt sent to Amazon Q is provided as follows.
"Based on this repo structure and the latest 5 Git commits, generate a README-style summary."

Role of Amazon Q Developer

Q Developer uses Claude-4-sonnet and other options (including Claude-3.7-sonnet and Claude-3.5-sonnet) to generate context-aware documentation, such as:
  • Repo description
  • Features
  • File architecture
  • Recent changes
  • Usage hints

Sample Output

Use Case

  • CI/CD integration with GitHub Actions
  • Automatically generate README files for hackathon projects
  • Sync documentation for internal tools or research repositories
  • Ideal for developers who move quickly and need to document efficiently

What I Learned

  • How to call Amazon Q CLI programmatically
  • Using child_process in Node.js to run terminal commands
  • Handling errors in Git and shell environments (like macOS's keychain prompt)
  • Creating an npm package from scratch and planning CI integrations

Problems I faced

The Claude-4 sonnet model employed for text summarization was frequently occupied. Transitioning to a lower-tier model is not as straightforward as it is in a command-line interface environment. However, it resulted in another interesting project utilizing Amazon Bedrock, which I will soon share here.

Do It Yourself

git clone https://github.com/DevABM/q-docgen.git
cd q-docgen
  • Install Amazon Q CLI Docs
  • Clone this repo Q-DocGen 
npm install
npm run docgen -- https://github.com/GitHub-Username/repo-name
  • Run it

Conclusion

This project demonstrated the significant capabilities of integrating GitHub, Amazon Q, and Node.js for automation purposes. With minimal coding effort, we transformed tedious manual documentation into an intelligent, repeatable workflow.
Developers should not be compelled to choose between rapid deployment and thorough documentation.
Utilizing Amazon Q eliminates this dilemma.
Thank you for your time. If you find this work interesting, please consider liking and sharing it. Follow me on LinkedIn , GitHub , Medium , or Dev 
# q-developer-challenge-1# amazon-q-developer# cli# developer-tools
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article