readme ai

README file generator, powered by AI.

eli64s
1629
170
Python

readme-ai-banner-logo

Designed for simplicity, customization, and developer productivity.

github-actions codecov pypi-version pepy-total-downloads license

🔗 Quick Links

  1. Overview
  2. Demo
  3. Features
  4. Getting Started
  5. Configuration
  6. Examples
  7. Contributing

[!IMPORTANT]
✨ Visit the Official Documentation for detailed guides and tutorials.

🔮 Overview

README-AI is a developer tool that automatically generates README markdown files using a robust repository processing engine and advanced language models. Simply provide a URL or path to your codebase, and a well-structured and detailed README will be generated.

Why README-AI?

This tool is designed to streamline the documentation process for developers, saving time and effort while ensuring high-quality README files. Key benefits include:

  • AI-Powered: Leverage language models for intelligent content generation.
  • Consistency: Ensure clean, standardized documentation across projects.
  • Customization: Tailor the output to fit your project’s requirements.
  • Language Agnostic: Works with most programming languages/frameworks.
  • Save Time: Generate comprehensive READMEs in less than a minute.

👾 Demo

Running from the command line:

readmeai-cli-demo

Running directly in your browser:

readmeai-streamlit-demo

☄️ Features

  • 🚀 Automated Documentation: Generate comprehensive README files automatically from your codebase.
  • 🎨 Customizable Output: Tailor the styling, formatting, badges, header designs, and more preferences.
  • 🤖 Flexible Backends: Seamlessly integrate with OpenAI, Ollama, Anthropic, Google Gemini.
  • 🌐 Language Agnostic: Compatible with a wide range of programming languages and project types.
  • 📑 Offline Mode: Create boilerplate README files offline, without any external API calls.
  • 📝 Best Practices: Ensures clean, professional documentation, adhering to markdown best practices.

Let’s take a look at some possible customizations created by readme-ai:

custom-dragon-project-logo
--image custom --badge-color FF4B4B --badge-style flat-square --header-style classic
docker-go-readme-example
--badge-color 00ADD8 --badge-style for-the-badge --header-style modern --toc-style roman

ascii-readme-header-style
--header-style ascii

svg-
--badge-style for-the-badge --header-style svg
readme-header-with-cloud-logo
--align left --badge-style flat-square --image cloud 		readme-header-with-gradient-markdown-logo
--align left --badge-style flat --image gradient
custom-balloon-project-logo
--badge-style flat --image custom 		readme-header-with-skill-icons-light
--badge-style skills-light --image grey
readme-header-with-blue-markdown-logo
--badge-style flat-square 		readme-header-with-black-readme-logo
--badge-style flat --image black

compact-readme-header
--image cloud --header-style compact --toc-style fold
readme-header-style-modern
-i custom -bc BA0098 -bs flat-square -hs modern -ts fold

[!IMPORTANT]
See the Official Documentation for more information on customization options and best practices.

Next, let’s explore the key sections of a typical README generated by readme-ai.

📍 Overview
Overview

◎ High-level introduction of the project, focused on the value proposition and use-cases, rather than technical aspects.

readme-overview-section
✨ Features
Features Table

◎ Generated markdown table that highlights the key technical features and components of the codebase. This table is generated using a structured prompt template.

readme-features-section
📃 Codebase Documentation
Directory Tree

◎ The project's directory structure is generated using pure Python and embedded in the README. See readmeai.generators.tree. for more details.

directory-tree
File Summaries

◎ Summarizes key modules of the project, which are also used as context for downstream prompts.

file-summaries
🚀 Quickstart Instructions
Getting Started Guides

◎ Prerequisites and system requirements are extracted from the codebase during preprocessing. The parsers handles the majority of this logic currently.

getting-started-section-prerequisites
Installation Guide

◎ Installation, Usage, and Testing guides are generated based on the project's dependency files and codebase configuration.

getting-started-section-usage-and-testing
🔰 Contributing Guidelines
Contributing Guide

◎ Dropdown section that outlines general process for contributing to your project.

◎ Provides links to your contributing guidelines, issues page, and more resources.

◎ Graph of contributors is also included.
contributing-guidelines-section
Additional Sections

◎ Roadmap, Contributing Guidelines, License, and Acknowledgements are included by default.

footer-readme-section

🛸 Getting Started

System Requirements

  • Python Version: 3.9 or higher
  • Package Management/Conainter Runtime: Choose one of the following:
    • pip: Python’s default package installer, recommended for most users.
    • pipx: Install and run readme-ai in an isolated environment.
    • uv: Fastest way to install readme-ai with a single command.
    • docker: Run readme-ai in a containerized environment.

Supported Repository Sources

The readmeai CLI can retrieve source code from the following Git hosting services or your local file system:

Platform Description Resource
File System Access repositories on your machine Learn more
GitHub World’s largest code hosting platform GitHub.com
GitLab Complete DevOps platform GitLab.com
Bitbucket Atlassian’s Git solution Bitbucket.org

Supported LLM API Providers

To unlock the full potential of readmeai, you’ll need an account and API key from one of the providers below:

Provider Description Resource
OpenAI Recommended for general use OpenAI Developer quickstart
Anthropic Advanced language models Anthropic Developer docs
Google Gemini Google’s multimodal AI model Gemini API quickstart
Ollama Free and open-source (No API key required) Ollama GitHub repository
Offline Mode Run readmeai without a LLM API Example offline mode README

⚙️ Installation

Choose your preferred installation method:

 Pip

Recommended method for most users:

❯ pip install readmeai

 Pipx

Use pipx to use readmeai in an isolated environment, ensuring no dependency conflicts with other Python projects:

❯ pipx install readmeai

 Uv

Use uv for the fastest way to install readmeai with a single command:

❯ uv tool install readmeai

 Docker

To run readmeai in a containerized environment, pull latest Docker image from Docker Hub:

❯ docker pull zeroxeli/readme-ai:latest

 From source

Click to expand instructions

  1. Clone the repository:

    ❯ git clone https://github.com/eli64s/readme-ai

  2. Navigate to the readme-ai directory:

    ❯ cd readme-ai

  3. Install dependencies:

    ❯ pip install -r setup/requirements.txt

Alternatively, the project can be setup using the bash script below:

 Bash

  1. Run the setup script:

    ❯ bash setup/setup.sh

Or, use poetry to build the project:

 Poetry

  1. Install dependencies using Poetry:

    ❯ poetry install

[!IMPORTANT]
To use the Anthropic and Google Gemini clients, extra dependencies are required. Install the package with the following extras:

  • Anthropic:

    ❯ pip install "readmeai[anthropic]"

  • Google Gemini:

    ❯ pip install "readmeai[google-generativeai]"

  • Install Multiple Clients:

    ❯ pip install "readmeai[anthropic,google-generativeai]"

🤖 Running the CLI

1. Set Up Environment Variables

With OpenAI:

❯ export OPENAI_API_KEY=<your_api_key>

# Or for Windows users:

❯ set OPENAI_API_KEY=<your_api_key>
Additional Providers (Ollama, Anthropic, Google Gemini)
Ollama

Refer to the Ollama documentation for more information on setting up the Ollama API. Here is a basic example:

  1. Pull your model of choice from the Ollama repository:

    ❯ ollama pull mistral:latest

  2. Start the Ollama server and set the OLLAMA_HOST environment variable:

    ❯ export OLLAMA_HOST=127.0.0.1 && ollama serve
Anthropic

  1. Export your Anthropic API key:

    ❯ export ANTHROPIC_API_KEY=<your_api_key>
Google Gemini

  1. Export your Google Gemini API key:

    ❯ export GOOGLE_API_KEY=<your_api_key

2. Generate a README

Run the following command, replacing the repository URL with your own:

❯ readmeai --repository https://github.com/eli64s/readme-ai --api openai

[!IMPORTANT]
By default, the gpt-3.5-turbo model is used. Higher costs may be incurred when more advanced models.

Run with Ollama and set llama3 as the model:

❯ readmeai --api ollama --model llama3 --repository https://github.com/eli64s/readme-ai

Run with Anthropic:

❯ readmeai --api anthropic -m claude-3-5-sonnet-20240620 -r https://github.com/eli64s/readme-ai

Run with Google Gemini:

❯ readmeai --api gemini -m gemini-1.5-flash -r https://github.com/eli64s/readme-ai

Use a local directory path:

readmeai --repository /path/to/your/project

Add 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

Run the Docker container with the OpenAI client:

❯ docker run -it --rm \
    -e OPENAI_API_KEY=$OPENAI_API_KEY \
    -v "$(pwd)":/app zeroxeli/readme-ai:latest \
    --repository https://github.com/eli64s/readme-ai \
    --api openai

 From source

Click to expand instructions

 Bash

If you installed the project from source with the bash script, run the following command:

  1. Activate the virtual environment:

    ❯ conda activate readmeai

  2. Run the CLI:

    ❯ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai

 Poetry

  1. Activate the virtual environment:

    ❯ poetry shell

  2. Run the CLI:

    ❯ poetry run python3 -m readmeai.cli.main -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.

🧪 Testing

The pytest and nox frameworks are used for development and testing.

Install the dependencies using Poetry:

❯ poetry install --with dev,test

Run the unit test suite using Pytest:

❯ make test

Run the test suite against Python 3.9, 3.10, 3.11, and 3.12 using Nox:

❯ make test-nox

[!TIP]
Nox is an automation tool that automates testing in multiple Python environments. It is used to ensure compatibility across different Python versions.

🔡 Configuration

Customize your README generation using these CLI options:

Option Description Default
--align Text alignment 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
--header-style Header template style classic
--toc-style Table of contents style bullet
--emojis Adds emojis to the README header sections False
--image Project logo image blue
--model Specific LLM model to use gpt-3.5-turbo
--output Output filename readme-ai.md
--repository Repository URL or local directory path None
--temperature Creativity level for content generation 0.1
--tree-depth Maximum depth of the directory tree structure 2

Run the following command to view all available options:

❯ readmeai --help

Visit the Official Documentation for more detailed information on configuration options, examples, and best practices.

🎨 Examples

View example README files generated by readme-ai across various Tech Stacks:

Technology Example Output Repository Description
Readme-ai readme-ai.md readme-ai Readme-ai project
Apache Flink readme-pyflink.md pyflink-poc Pyflink project
Streamlit readme-streamlit.md readme-ai-streamlit Streamlit web app
Vercel & NPM readme-vercel.md github-readme-quotes Vercel deployment
Go & Docker readme-docker-go.md docker-gs-ping Dockerized Go app
FastAPI & Redis readme-fastapi-redis.md async-ml-inference Async ML inference service
Java readme-java.md Minimal-Todo Minimalist todo Java app
PostgreSQL & DuckDB readme-postgres.md Buenavista Postgres proxy server
Kotlin readme-kotlin.md android-client Android client app
Offline Mode offline-mode.md litellm LLM API service

Find additional README examples in the examples directory.

🏎💨 Roadmap

  • [ ] Release readmeai 1.0.0 with enhanced documentation management features.
  • [ ] Develop Vscode Extension to generate README files directly in the editor.
  • [ ] Develop GitHub Actions to automate documentation updates.
  • [ ] Add badge packs to provide additional badge styles and options.
    • [ ] Code coverage, CI/CD status, project version, and more.

🔰 Contributing

Contributions are welcome! Please read the Contributing Guide to get started.


🙌 Acknowledgments

🎗 License

Copyright © 2023 readme-ai.

Released under the MIT License.