Awesome

<details><summary>Documentation</summary>

• Read the official readme-ai docs (🚧 WIP)

</details> <details><summary>Quick Links</summary>

• 📍 Overview
• 👾 Demo
• 🧬 Features
• 🚀 Getting Started
  • ⚙️ Installation
  • 🤖 Usage
  • 🧪 Testing
• 🔧 Configuration
• 🎨 Examples
• 🤝 Contributing

</details>

📍 Overview

Objective

Readme-ai is a developer tool that auto-generates README.md files using a combination of data extraction 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

Streamlines documentation creation and maintenance, enhancing developer productivity. This project aims to enable all skill levels, across all domains, to better understand, use, and contribute to open-source software.<br>

👾 Demo

CLI

readmeai-cli-demo

Streamlit

readmeai-streamlit-demo

[!TIP]

_{Check out this YouTube tutorial created by a community member!}

🧬 Features

• Flexible README Generation: Robust repository context extraction engine combined with generative AI.
• Customizable Output: Dozens of CLI options for styling/formatting, badges, header designs, and more.
• Language Agnostic: Works across a wide range of programming languages and project types.
• Multi-LLM Support: Compatible with OpenAI, Ollama, Google Gemini and Offline Mode.
  • Offline Mode: Generate a boilerplate README without calling an external API.

See a few examples of the README-AI customization options below:

See the <a href="https://github.com/eli64s/readme-ai?tab=readme-ov-file#-configuration">Configuration</a> section for a complete list of CLI options.

🚀 Getting Started

System Requirements:

• Python 3.9+
• Package manager/Container: pip, pipx, docker
• LLM service: OpenAI, Ollama, Google Gemini, Offline Mode
  • Anthropic and LiteLLM coming soon!

Repository URL or Local Path:

Make sure to have a repository URL or local directory path ready for the CLI.

• GitHub
• GitLab
• Bitbucket
• File System

Select an LLM API Service:

• OpenAI: Recommended, requires an account setup and API key.
• Ollama: Free and open-source, potentially slower and more resource-intensive.
• Google Gemini: Requires a Google Cloud account and API key.
• Offline Mode: Generates a boilerplate README without making API calls.

⚙️ Installation

Using pip

❯ pip install readmeai

Using pipx

❯ pipx install readmeai

[!TIP]

_{Use pipx to install and run Python command-line applications without causing dependency conflicts with other packages!}

Using docker

❯ docker pull zeroxeli/readme-ai:latest

From source

Clone repository and navigate to the project directory:

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

Using bash

❯ bash setup/setup.sh

Using poetry

❯ poetry install

🤖 Usage

Environment Variables

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 model of your choice from the Ollama registry as follows:

# i.e. mistral, llama3, gemma2, etc.
❯ ollama pull mistral:latest

Start the Ollama server:

❯ export OLLAMA_HOST=127.0.0.1 && ollama serve

_{For more details, check out the Ollama repository.}

Google Gemini

Generate a Google API key and set it as the environment variable GOOGLE_API_KEY.

❯ export GOOGLE_API_KEY=<your_api_key>

Running README-AI

Using pip

With OpenAI API:

❯ readmeai --repository https://github.com/eli64s/readme-ai \
        --api openai \
        --model gpt-3.5-turbo

With Ollama:

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

With Gemini:

❯ readmeai --repository https://github.com/eli64s/readme-ai \
        --api gemini
        --model gemini-1.5-flash

Advanced Options:

❯ readmeai --repository https://github.com/eli64s/readme-ai \
        --output readmeai.md \
        --api openai \
        --model gpt-4-turbo \
        --badge-color A931EC \
        --badge-style flat-square \
        --header-style compact \
        --toc-style fold \
        --temperature 0.1 \
        --tree-depth 2
        --image LLM \
        --emojis

Using docker

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

Using streamlit

_{Try directly in your browser on <a href="https://streamlit.io/">Streamlit</a>, no installation required! For more details, see the <a href="https://github.com/eli64s/readme-ai-streamlit">readme-ai-streamlit</a> repository.}

From source

Using bash

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

Using poetry

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

🧪 Testing

Using pytest

❯ make test

Using nox

❯ make test-nox

[!TIP]

_{Use nox to test application against multiple Python environments and dependencies!}

🔧 Configuration

Customize your README generation using these CLI options:

[!TIP] For a full list of options, run readmeai --help in your terminal.

Project Badges

The --badge-style option lets you select the style of the default badge set.

When providing the --badge-style option, readme-ai does two things:

1. Formats the default badge set to match the selection (i.e. flat, flat-square, etc.).
2. Generates an additional badge set representing your projects dependencies and tech stack (i.e. Python, Docker, etc.)

Example

❯ readmeai --badge-style flat-square --repository https://github.com/eli64s/readme-ai

Output

{... project logo ...}

{... project name ...}

{...project slogan...}

<img src="https://img.shields.io/github/license/eli64s/readme-ai?style=flat-square&color=0080ff&logo=opensourceinitiative&logoColor=white"> <img src="https://img.shields.io/github/last-commit/eli64s/readme-ai?style=flat-square&color=0080ff&logo=git&logoColor=white"> <img src="https://img.shields.io/github/languages/top/eli64s/readme-ai?style=flat-square&color=0080ff"> <img src="https://img.shields.io/github/languages/count/eli64s/readme-ai?style=flat-square&color=0080ff"> <br>

Developed with the software and tools below.

<img src="https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat-square&logo=GNU-Bash&logoColor=white"> <img src="https://img.shields.io/badge/tqdm-FFC107.svg?style=flat-square&logo=tqdm&logoColor=black"> <img src="https://img.shields.io/badge/Pydantic-E92063.svg?style=flat-square&logo=Pydantic&logoColor=white"> <img src="https://img.shields.io/badge/YAML-CB171E.svg?style=flat-square&logo=YAML&logoColor=white" alt="YAML"> <img src="https://img.shields.io/badge/Poetry-60A5FA.svg?style=flat-square&logo=Poetry&logoColor=white"> <img src="https://img.shields.io/badge/OpenAI-412991.svg?style=flat-square&logo=OpenAI&logoColor=white"> <br> <img src="https://img.shields.io/badge/Python-3776AB.svg?style=flat-square&logo=Python&logoColor=white"> <img src="https://img.shields.io/badge/AIOHTTP-2C5BB4.svg?style=flat-square&logo=AIOHTTP&logoColor=white"> <img src="https://img.shields.io/badge/Docker-2496ED.svg?style=flat-square&logo=Docker&logoColor=white"> <img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat-square&logo=GitHub-Actions&logoColor=white"> <img src="https://img.shields.io/badge/Pytest-0A9EDC.svg?style=flat-square&logo=Pytest&logoColor=white"> <br>

{... end of header ...}

Project Logo

Select a project logo using the --image option.

For custom images, see the following options:

• Use --image custom to invoke a prompt to upload a local image file path or URL.
• Use --image llm to generate a project logo using a LLM API (OpenAI only).

🎨 Examples

[!NOTE] See additional README file examples here.

📌 Roadmap

• v1.0 release with new features, bug fixes, and improved performance.
• Develop readmeai-vscode extension to generate README files (WIP).
• Add new CLI options to enhance README file customization.
  • --audit to review existing README files and suggest improvements.
  • --template to select a README template style (i.e. ai, data, web, etc.)
  • --language to generate README files in any language (i.e. zh-CN, ES, FR, JA, KO, RU)
• Develop robust documentation generator to build full project docs (i.e. Sphinx, MkDocs)
• Create community-driven templates for README files and gallery of readme-ai examples.
• GitHub Actions script to automatically update README file content on repository push.

📒 Changelog

Changelog

🤝 Contributing

To grow the project, we need your help! See the links below to get started.

• 🔰 Contributing Guide
• 👋 Start a Discussion
• 🐛 Open an Issue

🎗 License

MIT

👊 Acknowledgments

• Shields.io
• Aveek-Saha/GitHub-Profile-Badges
• Ileriayo/Markdown-Badges
• tandpfun/skill-icons