README file generator, powered by large language model APIs 👾
MIT License
[!IMPORTANT] ✨ See the Official Documentation for more details.
Objective
README-AI is a developer tool for automatically generating README markdown files using a robust repository processor engine and generative AI. Simply provide a repository URL or local path to your codebase, and a well-structured and detailed README file will be generated for you.
Motivation
This project aims to streamline the documentation process for developers, ensuring projects are properly documented and easy to understand. Whether you're working on an open-source project, enterprise software, or a personal project, README-AI is here to help you create high-quality documentation quickly and efficiently.
Running from the command line:
Running directly in your browser:
OpenAI
, Ollama
, Anthropic
, Google Gemini
and Offline Mode
.A few combinations of README styles and configurations:
See the Configuration section for a complete list of CLI options.
System Requirements:
3.9+
pip
, pipx
, docker
OpenAI
, Ollama
, Anthropic
, Google Gemini
, Offline Mode
Repository URL or Path:
Make sure to have a repository URL or local directory path ready for the CLI.
LLM API Service:
Install readme-ai using your preferred package manager, container, or directly from the source.
pip
❯ pip install readmeai
pipx
❯ pipx install readmeai
[! TIP]
Use pipx to install and run Python command-line applications without causing dependency conflicts with other packages!
docker
Pull the latest Docker image from the Docker Hub repository.
❯ docker pull zeroxeli/readme-ai:latest
source
bash
❯ bash setup/setup.sh
poetry
❯ git clone https://github.com/eli64s/readme-ai
readme-ai
directory:❯ cd readme-ai
poetry
:❯ poetry install
poetry
shell environment:❯ poetry shell
To use the Anthropic and Google Gemini clients, install the optional dependencies.
Anthropic:
❯ pip install readmeai[anthropic]
Google Gemini:
❯ pip install readmeai[gemini]
OpenAI
Generate a OpenAI API key and set it as the environment variable OPENAI_API_KEY
.
# Using Linux or macOS
❯ export OPENAI_API_KEY=<your_api_key>
# Using Windows
❯ set OPENAI_API_KEY=<your_api_key>
Ollama
Pull your model of choice from the Ollama repository:
❯ ollama pull mistral:latest
Start the Ollama server:
❯ export OLLAMA_HOST=127.0.0.1 && ollama serve
See all available models from Ollama here.
Anthropic
Generate an Anthropic API key and set the following environment variables:
❯ export ANTHROPIC_API_KEY=<your_api_key>
Google Gemini
Generate a Google API key and set the following environment variables:
❯ export GOOGLE_API_KEY=<your_api_key>
pip
With OpenAI:
❯ readmeai --api openai --repository https://github.com/eli64s/readme-ai
[! IMPORTANT] By default, the
gpt-3.5-turbo
model is used. Higher costs may be incurred when more advanced models.
With Ollama:
❯ readmeai --api ollama --model llama3 --repository https://github.com/eli64s/readme-ai
With Anthropic:
❯ readmeai --api anthropic -m claude-3-5-sonnet-20240620 -r https://github.com/eli64s/readme-ai
With Gemini:
❯ readmeai --api gemini -m gemini-1.5-flash -r https://github.com/eli64s/readme-ai
Adding more customization options:
❯ readmeai --repository https://github.com/eli64s/readme-ai \
--output readmeai.md \
--api openai \
--model gpt-4 \
--badge-color A931EC \
--badge-style flat-square \
--header-style compact \
--toc-style fold \
--temperature 0.9 \
--tree-depth 2
--image LLM \
--emojis
docker
Running the Docker container with the OpenAI API:
❯ docker run -it \
-e OPENAI_API_KEY=$OPENAI_API_KEY \
-v "$(pwd)":/app zeroxeli/readme-ai:latest \
-r https://github.com/eli64s/readme-ai
streamlit
Try readme-ai directly in your browser, no installation required. See the readme-ai-streamlit repository for more details.
source
bash
❯ conda activate readmeai
❯ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
poetry
❯ poetry shell
❯ poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
The pytest framework and nox automation tool are used for testing the application.
pytest
❯ make test
nox
❯ make test-nox
[!TIP] Use nox to test application against multiple Python environments and dependencies!
Customize your README generation using these CLI options:
Option | Description | Default |
---|---|---|
--align |
Text align in header | center |
--api |
LLM API service provider | offline |
--badge-color |
Badge color name or hex code | 0080ff |
--badge-style |
Badge icon style type | flat |
--base-url |
Base URL for the repository | v1/chat/completions |
--context-window |
Maximum context window of the LLM API | 3900 |
--emojis |
Adds emojis to the README header sections | False |
--header-style |
Header template style | classic |
--image |
Project logo image | blue |
--model |
Specific LLM model to use | gpt-3.5-turbo |
--output |
Output filename | readme-ai.md |
--rate-limit |
Maximum API requests per minute | 10 |
--repository |
Repository URL or local directory path | None |
--temperature |
Creativity level for content generation | 0.1 |
--toc-style |
Table of contents template style | bullet |
--top-p |
Probability of the top-p sampling method | 0.9 |
--tree-depth |
Maximum depth of the directory tree structure | 2 |
[!TIP] For a full list of options, run
readmeai --help
in your terminal.
To see the full list of customization options, check out the Configuration section in the official documentation. This section provides a detailed overview of all available CLI options and how to use them, including badge styles, header templates, and more.
Language/Framework | Output File | Input Repository | Description |
---|---|---|---|
Python | readme-python.md | readme-ai | Core readme-ai project |
TypeScript & React | readme-typescript.md | ChatGPT App | React Native ChatGPT app |
PostgreSQL & DuckDB | readme-postgres.md | Buenavista | Postgres proxy server |
Kotlin & Android | readme-kotlin.md | file.io Client | Android file sharing app |
Streamlit | readme-streamlit.md | readme-ai-streamlit | Streamlit UI for readme-ai app |
Rust & C | readme-rust-c.md | CallMon | System call monitoring tool |
Docker & Go | readme-go.md | docker-gs-ping | Dockerized Go app |
Java | readme-java.md | Minimal-Todo | Minimalist todo Java app |
FastAPI & Redis | readme-fastapi-redis.md | async-ml-inference | Async ML inference service |
Jupyter Notebook | readme-mlops.md | mlops-course | MLOps course repository |
Apache Flink | readme-local.md | Local Directory | Example using a local directory |
See additional README files generated by readme-ai here
readmeai 1.0.0
with enhanced documentation management features.Vscode Extension
to generate README files directly in the editor.GitHub Actions
to automate documentation updates.badge packs
to provide additional badge styles and options.
Contributions are welcome and encouraged! If interested, please begin by reviewing the resources below: