The talonhub/community repository contains over 5,000 lines of .talon files, making it challenging for both newcomers and experienced voice coders to fully grasp its capabilities. The written documentation (while valuable) barely scratches the surface, and the built-in help system operates at the same granularity as the .talon files. To address this, I developed repo-guide, an AI-powered tool that generates comprehensive, user-friendly guides to code repositories, with applications beyond just Talon.
Using repo-guide is straightforward: simply run repo-guide <path_to_repo> in your terminal to generate a Markdown guide and launch a local MkDocs server. The tool will thoroughly analyze and document each directory in the repository. For details on installation and usage, see the README.
I generated the talonhub/community guide using Gemini 2.0 Flash (currently free), though using Gemini 1.5 Flash would have cost less than 7 cents, processing under 1 million tokens. The resulting documentation is presented as a searchable MkDocs Material website with GitHub source code links throughout. It describes not only the Talon commands but also the tests and even the GitHub CI configuration.
Unlike traditional chat-based AI interfaces that respond to specific questions, repo-guide creates an exploratory learning experience, revealing answers to questions you might not have known to ask. It builds comprehensive documentation by analyzing each directory from the bottom up, incorporating file contents and its own subdirectory documentation into each prompt. This approach scales effectively and works well for repositories of various sizes and complexities.
Some of the trickiest problems I faced in creating this tool would have been the simplest in a traditional non-AI tool. Specifically, I had to try many different prompt formulations to get it to consistently generate correct links within its own docs and to files in GitHub. While these issues persist, they don’t diminish the tool’s ability to generate valuable documentation for complex repositories.
Future development plans:
- Changelog generation, incorporating both code changes and generated documentation. This will be useful for tracking improvements to talonhub/community.
- System prompt refinement. In the meantime, I encourage you to experiment with the
--custom-instructionsflag (or fork the repo) and try to improve the output! - Integration of a live chatbot for documentation queries. This could use both the documentation and the underlying code as context.
I welcome your feedback and suggestions for improving repo-guide. Try it out and let me know what you think in the comments!
Thank you. I wonder if it would be possible to do something similar for the APIs that Talon itself exposes like imgui and so. This way, we could create documentation on the functions Talon provides and those it doesn’t, to help AI models have reliable sources and not assume Talon-exposed functions that aren’t actually available. Would it be possible to do that? It would be like unofficial documentation about Talon itself.
That’s an interesting idea! I think you would need a slightly different technical approach because the codebase is not available, but I imagine an agent could go in and crawl through the APIs using the REPL and maybe even test them out and then write documentation.
I created this tool before coding agents existed, but if I were going to prototype that I would try just giving my coding agent the REPL and asking it to put this documentation together.
Thank you! If you could do that, it would be an enormous help.My skills are still limited. Often when I ask the coding agent to create a script for Talon, the lack of documentation or incorrect documentation leads to them inventing Talon APIs that have been deprecated. Having comprehensive documentation on Talon would make agents more efficient in adding new functionalities to Talon. Because the lack of documentation is one of Talon¨s main problem right now.