turbo-docs

turbo-docs: AI-powered, automatic README.md generator for your code repository, powered by OpenAI.

What is turbo-docs?
Features
Installation
Usage
How It Works
Supported Filetypes
Ignored Folders
Configuration
Example Output
Troubleshooting
Contributing
License

What is turbo-docs?

turbo-docs is a command-line tool that uses OpenAI’s powerful LLMs to automatically generate a comprehensive README.md for your code project. It recursively analyzes your codebase, identifies important files, and crafts high-quality, context-aware project documentation—so you can focus on building.

Features

Automatic README Generation: Scans your code and produces a usable README.md using OpenAI.
Recursively Scans Your Codebase: Finds source and config files, skipping irrelevant/large ones.
Smart Filtering: Only includes meaningful files (by extension, size, and folder).
Chain-of-Thought Process: Structures the README like an expert would think it through.
Streaming Generation: Watch your README generated live as you run the tool.
Easy CLI Usage: One simple command to generate documentation.
Safe: Never includes sensitive environment files or your existing README.md.

Installation

Requirements:

Python 3.11 or newer
PDM for dependency management
OpenAI API key

Steps:

Clone or Download this repository.
Install dependencies:
```
pdm install
```
Set your OpenAI API key (required):
- Add your API key to a .env file in your project root:
```
OPENAI_API_KEY=sk-...
```
- Or export it in your shell:
```
export OPENAI_API_KEY=sk-...
```
(Optional) Install CLI script globally:
```
pdm run pip install .
```

Usage

From your project's root directory, run:

pdm run turbo-docs --readme

This command will ingest your codebase, interact with OpenAI, and generate a README.md in the current directory.
Alternatively, after pip installation, you can run:
```
turbo-docs --readme
```

Command-line options:

--readme Generate or overwrite the README.md for your repository.

How It Works

Recursively scans the current directory for relevant files:
- Skips ignored folders (see below).
- Only includes files with allowed extensions.
- Skips large files and files that are not text.
- Ignores any existing README.md.
Prepares the context: Parses and combines relevant code/config into a single input.
Invokes OpenAI LLM:
- Generates a detailed "chain-of-thought" for writing a great README.
- Streams the final README content directly into README.md.
Saves the generated README.md for you to review, edit, or publish!

Supported Filetypes

turbo-docs considers a broad range of files from various programming ecosystems. Supported extensions include:

Code: .py, .js, .ts, .tsx, .cpp, .java, .go, .rs, .rb, .php, .c, .cs, .swift, .kt, .scala, .dart, .lua, .r etc.
Markup/Docs: .md, .mdx, .rst, .tex, .adoc, .org, .wiki, .textile, etc.
Configs/Manifests: .json, .toml, .yaml, .yml, .ini
Shell & Scripts: .sh, .bat, .cmd, .ps1
Templates: .j2, .jinja, .tpl, etc.

Full extension list (click to expand):

.js, .jsx, .ts, .tsx, .vue, .svelte, .html, .css, .scss, .sass, .less, .py, .java, .cpp, .c, .cs, .go, .rs, .rb, .php, .scala, .kt, .kts, .groovy, .swift, .m, .h, .hpp, .cxx, .cc, .hh, .perl, .pl, .pm, .sh, .bash, .zsh, .fish, .ps1, .bat, .cmd, .toml, .ini, .json, .yaml, .yml, .j2, .jinja, .jinja2, .tmpl, .tpl, .md, .mdx, .rst, .tex, .adoc, .asciidoc, .wiki, .org, .pod, .rdoc, .textile, .creole, .dokuwiki, .mediawiki, .r, .lua, .dart, .elm, .ex, .exs, .erl, .hrl, .clj, .cls, .asm, .s, .nim, .cr, .ml, .mli, .fs, .fsx

Ignored Folders

turbo-docs intentionally skips standard folders that typically contain dependencies or build artifacts:

node_modules
dist
build
public
static
templates
vendor
venv
env
cache
tmp
temp

In addition, any folder or file starting with a dot (.) is ignored.

Configuration

API Key:
You must provide your OPENAI_API_KEY in your environment. Set it either in a .env file or export it using your shell, as shown in Installation.
Customization:
For now, turbo-docs has minimal CLI options (just --readme). Future versions may support more config options!

Example Output

Here’s an excerpt from a README generated by turbo-docs running on itself:

# turbo-docs

turbo-docs is a command-line utility that generates high-quality README.md files for your code repository using OpenAI's LLMs. It recursively scans your codebase, selects important files by type and size, excludes irrelevant folders, and synthesizes a professional project overview auto-magically.

## Features

- Automatic README generation using AI
- Supports dozens of code, config, and markup file types
- Excludes large or generated files and folders
- CLI-driven, easy to use

## Installation

...

_{(Real output will be more complete—give it a try!)}

Troubleshooting

Common Issues:

OPENAI_API_KEY not set:
- Make sure your API key is in your .env or exported in your environment.
- If you see an error like:
  Looks like you are missing the OPENAI_API_KEY environment variable.
  Follow the Installation instructions to set it.
Wrong Python version: Python 3.11+ is required.
No README generated: Ensure you are in your project root and that your code files use supported extensions.

If issues persist, check error messages printed by the tool.

Contributing

Pull requests, issues, and suggestions are welcome!

Author: voynow
Please ensure your code adheres to the style guide and is well-documented.
Open a GitHub issue for any bug, or feature request.

License

MIT License
Copyright (c) voynow

Enjoy blazing-fast, AI-powered docs with turbo-docs! 🚀

Release files for turbo-docs 2.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for turbo-docs 2.0.8
File	Size	Uploaded
turbo_docs-2.0.8.tar.gz	7.3 kB	Jun 15, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for turbo-docs 2.0.8
File	Interpreter	ABI	Platform	Reset
turbo_docs-2.0.8-py3-none-any.whl 8.7 kB Jun 15, 2025	Python 3	none	any	Details

Total release size: 16.0 kB

Release files / turbo_docs-2.0.8.tar.gz

Download URL	turbo_docs-2.0.8.tar.gz
Size	7.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`e30c454ecb7e753bc72d9686811a2e3762ec9126cc070422066f3f18afb4227a`
BLAKE2b-256 checksum How to use checksums	`67da1ba44e9147bb1e7557e83fb1a416c2fb4c47bfe39a351ee2d40a5f91e88a`
Upload date	Jun 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`pdm/2.25.1 CPython/3.12.3 Linux/6.11.0-1015-azure`

Release files / turbo_docs-2.0.8-py3-none-any.whl

Download URL	turbo_docs-2.0.8-py3-none-any.whl
Size	8.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`30402fb552427bc9b60cc1463d3a5e5ca1e2f443ede2a9bdd5b531cda865caff`
BLAKE2b-256 checksum How to use checksums	`ccc55dab5cfd04ce74b77673daa37aabbac2ce6f30fbb392aff0d1b70e8e0c9f`
Upload date	Jun 15, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`pdm/2.25.1 CPython/3.12.3 Linux/6.11.0-1015-azure`