Code-Narrator: Automating Documentation with GPT-4

As a solo developer on a sizeable project, I found myself facing the challenge of creating documentation, a task I admittedly do not enjoy. Fortunately, ChatGPT arrived just in time. After experimenting with it, I discovered that it generates high-quality documentation for code files, even better than what I could produce manually. This realization led me to develop Code-Narrator, a client that simplifies the documentation process.

Code-Narrator (GitHub - ingig/code-narrator: Self documenting tool using GPT4. It also can document your project) utilizes GPT-4 to analyze your code files and automatically generate documentation. The tool is language-agnostic and has been tested with TypeScript, GraphQL, Solidity, C#, Kotlin, and more. As long as the files are in plain text, Code-Narrator should work seamlessly.

The primary goal of Code-Narrator is to ease the documentation process for developers, transforming them from writers to editors. While developers are still responsible for verifying the accuracy of the generated documentation, the initial writing is handled by the AI.

If GPT-4 produces incorrect documentation, it typically indicates that the code needs clarification, or a brief comment should be added to guide the AI. A general rule of thumb is that if GPT-4 cannot comprehend the code, it may be too complex for the next developer.

However, Code-Narrator is constrained by GPT-4’s 8192-token limit, which can be problematic for extensive code files. Those with access to the gpt-4-32k variant should expect better results, as the quality of the generated documentation heavily depends on the length of the input (question + file content).

Upon its first run, Code-Narrator creates a configuration file by analyzing your project, and then prompts you to review it for accuracy. The key configuration aspects include the “include,” “config_files,” and “source_path” settings.

In its second run, Code-Narrator generates documentation for your entire project. The process is time-consuming, taking approximately 45 minutes to complete from scratch. However, the tool is:

  • Flexible, allowing for the creation of custom pages such as How-To guides, tutorials, FAQs, READMEs, and other bespoke content.
  • Multilingual, supporting 25+ languages (as many as GPT-4 supports).
  • Versatile, capable of generating documentation in various formats (LaTeX, HTML, with the default being Markdown).

For a demonstration on transforming a few lines into a How-To guide, watch this video: Code narrator - howto create a howto guide - YouTube. Remember that brevity is key, as the more concise the input, the more GPT-4 can contribute.

In terms of size and cost, Code-Narrator consists of 45 files and 1712 lines of code. The total cost of generating documentation for the entire project is approximately $2.5, a significant savings compared to manual documentation.

During the development of Code-Narrator, I noticed several benefits:

  • Improved function naming: Reading the generated documentation led me to revise vague or overly general function names, resulting in better code and documentation.
  • Concise input: Focusing on reducing the size of the input file (liquid) became a fun challenge, helping to optimize the process.
  • Enjoyable interaction: Working with ChatGPT proved more enjoyable than manually writing documentation, and the more I experimented, the better the results.
  • Minimal input for tutorials: I was pleasantly surprised by how little input was required to create How-To guides and tutorials using GPT-4.
  • Encouragement to refactor: The 8K token limitation may be restrictive, but it also encourages developers to refactor their code for improved readability and structure.

As a prototype and proof of concept, Code-Narrator has some limitations. Future improvements and features I’d like to implement include:

  • Documenting only diffs in files.
  • Building a static website using Jekyll or Docusaurus (time constraints have prevented completion thus far).
  • Adding unit tests for the project.
  • Generating comprehensive documentation for unit tests.
  • Enhancing the generation of Mermaid charts using GPT-4, as this has shown promise in initial tests.
  • Implementing better caching to reduce costs.

I’m excited to see where Code-Narrator goes from here, and your feedback is invaluable. Thank you for taking the time to explore this project!


Thank you for sharing this project! I had a similar need (and idea), and will definitely be trying it out.

btw - what license is the code being released under?

It’s ISC.

Hope the project can help out in anyway