Awesome

🔗 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.
• 🌐 Language Agnostic: Compatible with a wide range of programming languages and project types.
• 🤖 Multi-LLM Support: Current support for OpenAI, Ollama, Anthropic, Google Gemini.
• 📑 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:

[!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.

🛸 Getting Started

System Requirements

• Python: 3.9+
• Package Manager/Container: pip, pipx, uv, or docker.

Supported Sources

The following git hosting services are supported for source code retrieval, along with your local file system:

• GitHub
• GitLab
• Bitbucket
• File System

Supported LLM APIs

To enable the full functionality of readmeai, an account and API key are required for one of the following providers:

• OpenAI: Recommended for general use. Requires an OpenAI account and API key.
• Ollama: Free and open-source. No API key required.
• Anthropic: Requires an Anthropic account and API key.
• Google Gemini: Requires a Google Cloud account and API key.
• Offline Mode: Generates a README without making API calls.

_{For more information on setting up an API key, refer to the provider's documentation.}

⚙️ Installation

Choose your preferred installation method:

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/python.svg"> Pip

❯ pip install readmeai

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/pipx.svg"> Pipx

❯ pipx install readmeai

[!TIP] _{Using pipx allows you to install and run Python command-line applications in isolated environments, which helps prevent dependency conflicts with other Python projects.}

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/3052baaca03db99d00808acfec43a44e81ecbf7f/docs/docs/assets/svg/docker.svg"> Docker

Pull the latest Docker image from the Docker Hub repository.

❯ docker pull zeroxeli/readme-ai:latest

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/git.svg"> From source

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:

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/gnubash.svg"> Bash

1. Run the setup script:

   ❯ bash setup/setup.sh
   

Or, use poetry to build the project:

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/poetry.svg"> Poetry

1. Install dependencies using Poetry:

   ❯ poetry install
   

[!IMPORTANT] To use the Anthropic and Google Gemini clients, additional dependencies are required. See the following installation commands:

• Anthropic:

  ❯ pip install "readmeai[anthropic]"
  

• Google Gemini:

  ❯ pip install "readmeai[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>

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
   

1. Export your Anthropic API key:

   ❯ export ANTHROPIC_API_KEY=<your_api_key>
   

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

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/3052baaca03db99d00808acfec43a44e81ecbf7f/docs/docs/assets/svg/docker.svg"> 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

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/git.svg"> From source

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/gnubash.svg"> 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
   

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/poetry.svg"> 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
   

<img width="2%" src="https://raw.githubusercontent.com/eli64s/readme-ai/5ba3f704de2795e32f9fdb67e350caca87975a66/docs/docs/assets/svg/streamlit.svg"> Streamlit

Try readme-ai directly in your browser, no installation required. See the <a href="https://github.com/eli64s/readme-ai-streamlit">readme-ai-streamlit</a> repository for more details.

<img align="center" src="https://static.streamlit.io/badges/streamlit_badge_black_white.svg" width="20%">

🧪 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:

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:

_{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.

• 💡 Contributing Guide: Learn about our contribution process and coding standards.
• 🐛 Report an Issue: Found a bug? Let us know!
• 💬 Start a Discussion: Have ideas or suggestions? We'd love to hear from you.

🎗 License

README-AI is released under the terms of the MIT License.

🙌 Acknowledgments

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