GitHub - eli64s/readme-ai: README file generator, powered by AI.

README-AI, Your AI-Powered Documentation Assistant

Designed for simplicity, customization, and developer productivity.

🔗 Quick Links

Important

✨ See theOfficial Documentationfor 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.mov

Running directly in your browser:

readmeai-streamlit-demo.mov

☄️ 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 withOpenAI,Ollama,Anthropic,Google GeminiandOffline 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:

`--image custom --badge-color FF4B4B --badge-style flat-square --header-style classic`
`--image cloud --header-style compact --toc-style fold`
`--align left --badge-style flat-square --image cloud`	`--align left --badge-style flat --image gradient`
`--badge-style flat --image custom`	`--badge-style skills-light --image grey`
`--badge-style flat-square`	`--badge-style flat --image black`
`--image custom --badge-color 00ffe9 --badge-style flat-square --header-style classic`
`--image llm --badge-style plastic --header-style classic`
`--image custom --badge-color BA0098 --badge-style flat-square --header-style modern --toc-style fold`

See theConfigurationsection 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.

✨ Features

Features Table

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

📃 Codebase Documentation

Directory Tree

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

File Summaries

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

🚀 Quickstart Instructions

Getting Started Guides

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

Installation Guide

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

🔰 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.

Additional Sections

◎Project Roadmap,Contributing Guidelines,License,andAcknowledgementsare included by default.

🛸 Getting Started

System Requirements:

Python3.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 install readmeai

Using`pipx`

❯ pipx install readmeai

[! TIP]

_{Usepipxto 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 pull zeroxeli/readme-ai:latest

From`source`

Build readme-ai

Using`bash`

❯ bash setup/setup.sh

Using`poetry`

Clone the repository:

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

Navigate to thereadme-aidirectory:

❯cdreadme-ai

Install dependencies usingpoetry:

❯ poetry install

Enter thepoetryshell environment:

❯ poetry shell

Installing Optional Dependencies

To use theAnthropicandGoogle Geminiclients, 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 variableOPENAI_API_KEY.

#Using Linux or macOS
❯exportOPENAI_API_KEY=<your_api_key>

#Using Windows
❯setOPENAI_API_KEY=<your_api_key>

Ollama

Pull your model of choice from the Ollama repository:

❯ ollama pull mistral:latest

Start the Ollama server:

❯exportOLLAMA_HOST=127.0.0.1&&ollama serve

_{See all available models from Ollamahere.}

Anthropic

Generate an Anthropic API key and set the following environment variables:

❯exportANTHROPIC_API_KEY=<your_api_key>

Google Gemini

Generate a Google API key and set the following environment variables:

❯exportGOOGLE_API_KEY=<your_api_key>

Running the CLI

Using`pip`

With OpenAI:

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

[! IMPORTANT] By default, thegpt-3.5-turbomodel is used. Higher costs may be incurred when more advanced models.

With Ollama:

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

With Anthropic:

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

With Gemini:

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

Adding more customization options:

❯ readmeai --repository https://github /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 run -it \
-e OPENAI_API_KEY=$OPENAI_API_KEY\
-v"$(pwd)":/app zeroxeli/readme-ai:latest \
-r https://github /eli64s/readme-ai

Using`streamlit`

Try readme-ai directly in your browser, no installation required. See thereadme-ai-streamlitrepository for more details.

From`source`

Using readme-ai

Using`bash`

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

Using`poetry`

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

🧪 Testing

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

Using`pytest`

❯ maketest

Using`nox`

❯ make test-nox

Tip

_{Usenoxto 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, runreadmeai --helpin your terminal.

🎨 Customization

To see the full list of customization options, check out theConfigurationsection 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-aihere}

🏎💨 Project Roadmap

Releasereadmeai 1.0.0with enhanced documentation management features.
DevelopVscode Extensionto generate README files directly in the editor.
DevelopGitHub Actionsto automate documentation updates.
Addbadge packsto 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

Name		Name	Last commit message	Last commit date
Latest commit History 690 Commits
.github		.github
docs		docs
examples		examples
readmeai		readmeai
scripts		scripts
setup		setup
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.ruff.toml		.ruff.toml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
mkdocs.yml		mkdocs.yml
noxfile.py		noxfile.py
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

License

eli64s/readme-ai

Folders and files

Latest commit

History

Repository files navigation

README-AI, Your AI-Powered Documentation Assistant

🔗 Quick Links

⚡️ Introduction

👾 Demo

☄️ Features

🛸 Getting Started

🔩 Installation

Usingpip

Usingpipx

Usingdocker

Fromsource

Usingbash

Usingpoetry

Installing Optional Dependencies

⚙️ Usage

Environment Variables

Running the CLI

Usingpip

Usingdocker

Usingstreamlit

Fromsource

Usingbash

Usingpoetry

🧪 Testing

Usingpytest

Usingnox

🔡 Configuration

🎨 Customization

🤖 Examples

🏎💨 Project Roadmap

🔰 Contributing

📒 Changelog

🎗 License

🙌 Acknowledgments

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 16

Packages 0

Contributors 4

Languages

Using`pip`

Using`pipx`

Using`docker`

From`source`

Using`bash`

Using`poetry`

Using`pip`

Using`docker`

Using`streamlit`

From`source`

Using`bash`

Using`poetry`

Using`pytest`

Using`nox`

Packages