readme-ai

readme-ai

README file generator, powered by AI.

Stars: 1491

Visit
 screenshot

README-AI is a developer tool that auto-generates README.md files using a combination of data extraction and generative AI. It 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. It offers flexible README generation, supports multiple large language models (LLMs), provides customizable output options, works with various programming languages and project types, and includes an offline mode for generating boilerplate README files without external API calls.

README:

README-AI, Your AI-Powered Documentation Assistant

Designed for simplicity, customization, and developer productivity.

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


๐Ÿ”— Quick Links

  1. โšก๏ธ Introduction
  2. ๐Ÿ‘พ Demo
  3. โ˜„๏ธ Features
  4. ๐Ÿ›ธ Quickstart
  5. ๐Ÿ”ก Configuration
  6. ๐Ÿค– Examples
  7. ๐Ÿ”ฐ Contributing

[!IMPORTANT] โœจ See the Official Documentation for more details.


โšก๏ธ Introduction

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.


๐Ÿ‘พ Demo

Running from the command line:

readmeai-cli-demo

Running directly in your browser:

readmeai-streamlit-demo


โ˜„๏ธ Features

  • Automated Documentation: Synchronize data from third-party sources and generates documentation automatically.
  • Customizable Output: Dozens of 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, Anthropic, Google Gemini and Offline Mode.
  • Offline Mode: Generate a boilerplate README without calling an external API.
  • Markdown Best Practices: Leverage best practices in Markdown formatting for clean, professional-looking docs.

A few combinations of README styles and configurations:

custom-project-logo
--image custom --badge-color FF4B4B --badge-style flat-square --header-style classic


--image cloud --header-style compact --toc-style fold
cloud-db-logo
--align left --badge-style flat-square --image cloud
gradient-markdown-logo
--align left --badge-style flat --image gradient
custom-logo
--badge-style flat --image custom
skills-light
--badge-style skills-light --image grey
readme-ai-header
--badge-style flat-square
black-logo
--badge-style flat --image black
default-header
--image custom --badge-color 00ffe9 --badge-style flat-square --header-style classic
default-header
--image llm --badge-style plastic --header-style classic
default-header
--image custom --badge-color BA0098 --badge-style flat-square --header-style modern --toc-style fold

See the Configuration section for a complete list of CLI options.

๐Ÿ“ Overview
Overview

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

llm-overview
โœจ 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.

llm-features
๐Ÿ“ƒ 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.

prerequisites
Installation Guide

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

installation
๐Ÿ”ฐ 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
Additional Sections

โ—Ž Project Roadmap, Contributing Guidelines, License, and Acknowledgements are included by default.

footer

๐Ÿ›ธ Getting Started

System Requirements:

  • Python 3.9+
  • Package Manager/Container: pip, pipx, docker
  • LLM API Service: 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:

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

๐Ÿ”ฉ Installation

Install readme-ai using your preferred package manager, container, or directly from the source.

Using pip

pip

โฏ pip install readmeai

Using pipx

pipx

โฏ pipx install readmeai

[! TIP]

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

Using docker

Pull the latest Docker image from the Docker Hub repository.

docker

โฏ docker pull zeroxeli/readme-ai:latest

From source

Build readme-ai

Using bash

bash

โฏ bash setup/setup.sh

Using poetry

Poetry

  1. Clone the repository:
โฏ git clone https://github.com/eli64s/readme-ai
  1. Navigate to the readme-ai directory:
โฏ cd readme-ai
  1. Install dependencies using poetry:
โฏ poetry install
  1. Enter the poetry shell environment:
โฏ poetry shell

Installing Optional Dependencies

To use the Anthropic and Google Gemini clients, install the optional dependencies.

Anthropic:

โฏ pip install readmeai[anthropic]

Google Gemini:

โฏ pip install readmeai[gemini]

โš™๏ธ 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 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>

Running the CLI

Using pip

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

Using docker

Running the Docker container with the OpenAI API:

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 readme-ai directly in your browser, no installation required. See the readme-ai-streamlit repository for more details.

From source

Using readme-ai

Using bash

bash

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

Using poetry

Poetry

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

๐Ÿงช Testing

The pytest framework and nox automation tool are used for testing the application.

Using pytest

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:

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.

๐ŸŽจ Customization

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.


๐Ÿค– Examples

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


๐ŸŽ๐Ÿ’จ Project 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 and encouraged! If interested, please begin by reviewing the resources below:

  • ๐Ÿ’ก Contributing Guide: Learn about our contribution process, coding standards, and how to submit your ideas.
  • ๐Ÿ’ฌ Start a Discussion: Have questions or suggestions? Join our community discussions to share your thoughts and engage with others.
  • ๐Ÿ› Report an Issue: Found a bug or have a feature request? Let us know by opening an issue so we can address it promptly.


๐Ÿ“’ Changelog

Changelog


๐ŸŽ— License

MIT License


๐Ÿ™Œ Acknowledgments

โฌ†๏ธ Top


For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for readme-ai

Similar Open Source Tools

For similar tasks

For similar jobs