Home

Awesome

<p align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/svg/readme-ai-gradient.svg" alt="readme-ai-banner-logo" width="80%"> </p> <p align="center"> <em>Designed for simplicity, customization, and developer productivity.</em> </p> <p align="center"> <a href="https://github.com/eli64s/readme-ai/actions"> <img src="https://img.shields.io/github/actions/workflow/status/eli64s/readme-ai/release-pipeline.yml?logo=githubactions&label=CICD&logoColor=white&color=4169E1" alt="github-actions"> </a> <a href="https://app.codecov.io/gh/eli64s/readme-ai"> <img src="https://img.shields.io/codecov/c/github/eli64s/readme-ai?logo=codecov&logoColor=white&label=Coverage&color=5D4ED3" alt="codecov"> </a> <a href="https://pypi.python.org/pypi/readmeai/"> <img src="https://img.shields.io/pypi/v/readmeai?logo=Python&logoColor=white&label=PyPI&color=7934C5" alt="pypi-version"> </a> <a href="https://www.pepy.tech/projects/readmeai"> <img src="https://img.shields.io/pepy/dt/readmeai?logo=PyPI&logoColor=white&label=Downloads&color=9400D3" alt="pepy-total-downloads"> </a> <a href="https://opensource.org/license/mit/"> <img src="https://img.shields.io/github/license/eli64s/readme-ai?logo=opensourceinitiative&logoColor=white&label=License&color=8A2BE2" alt="license"> </a> </p>

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


👾 Demo

Running from the command line:

readmeai-cli-demo

Running directly in your browser:

readmeai-streamlit-demo


☄️ Features

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

<table> <!-- ROW --> <tr> <td colspan="2" align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/custom-dragon.png" alt="custom-dragon-project-logo" width="700"> <br> <code>--image custom --badge-color FF4B4B --badge-style flat-square --header-style classic</code> </td> </tr> <!-- ROW --> <tr> <td colspan="2" align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/toc/roman-numeral.png" alt="docker-go-readme-example" width="700"> <br> <code>--badge-color 00ADD8 --badge-style for-the-badge --header-style modern --toc-style roman</code> </td> </tr> <!-- ROW --> <tr> <td colspan="2" align="center"><br> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/ascii-art.png" alt="ascii-readme-header-style" width="700"> <br> <code>--header-style ascii</code> </td> </tr> <!-- ROW --> <tr> <td colspan="2" align="center"><br> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/svg-banner.png" alt="svg-" width="700"> <br> <code>--badge-style for-the-badge --header-style svg</code> </td> </tr> <!-- ROW --> <tr> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/refs/heads/main/docs/docs/assets/img/headers/cloud.png" alt="readme-header-with-cloud-logo" width="350"> <br> <code>--align left --badge-style flat-square --image cloud</code> </td> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/refs/heads/main/docs/docs/assets/img/headers/gradient.png" alt="readme-header-with-gradient-markdown-logo" width="350"> <br> <code>--align left --badge-style flat --image gradient</code> </td> </tr> <!-- ROW --> <tr> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/custom-balloon.png" alt="custom-balloon-project-logo" width="350"> <br> <code>--badge-style flat --image custom</code> </td> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/skill-icons-light.png" alt="readme-header-with-skill-icons-light" width="350"> <br> <code>--badge-style skills-light --image grey</code> </td> </tr> <!-- ROW --> <tr> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/blue.png" alt="readme-header-with-blue-markdown-logo" width="350"> <br> <code>--badge-style flat-square</code> </td> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/black.png" alt="readme-header-with-black-readme-logo" width="350"> <br> <code>--badge-style flat --image black</code> </td> </tr> <!-- ROW --> <tr> <td colspan="2" align="center"><br> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/headers/compact.png" alt="compact-readme-header" width="700"> <br> <code>--image cloud --header-style compact --toc-style fold</code> </td> </tr> <!-- ROW --> <tr> <td colspan="2" align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/refs/heads/main/docs/docs/assets/img/headers/modern-flat-square.png" alt="readme-header-style-modern" width="700"> <br> <code>-i custom -bc BA0098 -bs flat-square -hs modern -ts fold</code> </td> </tr> </table>

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

<details closed> <summary><strong>📍 Overview</strong></summary><br> <table> <tr> <td> <b>Overview</b><br> <p>◎ High-level introduction of the project, focused on the value proposition and use-cases, rather than technical aspects. </p> </td> </tr> <tr> <td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/llm-content/overview.png" alt="readme-overview-section" width="700"> </td> </tr> </table> </details> <details closed> <summary><strong>✨ Features</strong></summary><br> <table> <tr> <td><b>Features Table</b><br> <p>◎ Generated markdown table that highlights the key technical features and components of the codebase. This table is generated using a structured <a href="https://github.com/eli64s/readme-ai/blob/main/readmeai/config/settings/prompts.toml">prompt template.</a> </p> </td> </tr> <tr> <td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/llm-content/features-table.png" alt="readme-features-section" width="700"> </td> </tr> </table> </details> <details closed> <summary><strong>📃 Codebase Documentation</strong></summary><br> <table> <tr> <td><b>Directory Tree</b><br> <p>◎ The project's directory structure is generated using pure Python and embedded in the README. See <a href="https://github.com/eli64s/readme-ai/blob/main/readmeai/generators/tree.py">readmeai.generators.tree.</a> for more details. </p> </td> </tr> <tr> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/project-structure/tree.png" alt="directory-tree" width="700"> </td> </tr> <tr> <td style="padding-top:20px;"> <b>File Summaries</b><br> <p>◎ Summarizes key modules of the project, which are also used as context for downstream <a href="https://github.com/eli64s/readme-ai/blob/main/readmeai/config/settings/prompts.toml">prompts.</a> </p> </td> </tr> <tr> <td align="center"> <img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/project-structure/file-summaries.png" alt="file-summaries" width="700"> </tr> </table> </details> <details closed> <summary><strong>🚀 Quickstart Instructions</strong></summary> <br> <table> <tr> <td><b>Getting Started Guides</b><br> <p>◎ Prerequisites and system requirements are extracted from the codebase during preprocessing. The <a href="https://github.com/eli64s/readme-ai/tree/main/readmeai/parsers">parsers</a> handles the majority of this logic currently. </p> </td> </tr> <tr> <td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/getting-started/prerequisites-and-installation.png" alt="getting-started-section-prerequisites" width="700"> </td> </tr> <tr> <td><b>Installation Guide</b><br> <p>◎ <code>Installation</code>, <code>Usage</code>, and <code>Testing</code> guides are generated based on the project's dependency files and codebase configuration. </p> <tr> <td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/getting-started/usage-and-testing.png" alt="getting-started-section-usage-and-testing" width="700"> </td> </tr> </table> </details> <details closed> <summary><strong>🔰 Contributing Guidelines</strong></summary> <br> <table> <tr> <td><b>Contributing Guide</b><br> <p>◎ Dropdown section that outlines general process for contributing to your project.</p> <p>◎ Provides links to your contributing guidelines, issues page, and more resources.</p> <p>◎ Graph of contributors is also included.</p> </p> </td> </tr> <tr> <td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/contributing/contributing-guidelines.png" alt="contributing-guidelines-section" width="700"> </td> </tr> <tr> <td><b>Additional Sections</b><br> <p>◎ <code>Roadmap</code>, <code>Contributing Guidelines</code>, <code>License</code>, and <code>Acknowledgements</code> are included by default. </p> </td> </tr> <tr> <td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/docs/docs/assets/img/contributing/footer.png" alt="footer-readme-section" width="700"></td> </tr> </table> </details>

🛸 Getting Started

System Requirements

Supported Repository Sources

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

PlatformDescriptionResource
File SystemAccess repositories on your machineLearn more
GitHubWorld's largest code hosting platformGitHub.com
GitLabComplete DevOps platformGitLab.com
BitbucketAtlassian's Git solutionBitbucket.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:

ProviderDescriptionResource
OpenAIRecommended for general useOpenAI Developer quickstart
AnthropicAdvanced language modelsAnthropic Developer docs
Google GeminiGoogle's multimodal AI modelGemini API quickstart
OllamaFree and open-source (No API key required)Ollama GitHub repository
Offline ModeRun readmeai without a LLM APIExample offline mode README

⚙️ Installation

Choose your preferred installation method:

<!-- #### Using `pip` [![pip](https://img.shields.io/badge/PyPI-3775A9.svg?style=flat&logo=PyPI&logoColor=white)](https://pypi.org/project/readmeai/) -->

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

Recommended method for most users:

❯ pip install readmeai
<!-- #### Using `pipx` [![pipx](https://img.shields.io/badge/pipx-2CFFAA.svg?style=flat&logo=pipx&logoColor=black)](https://pipxproject.github.io/pipx/installation/) -->

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

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

❯ pipx install readmeai
<!-- > [!TIP] > <sub>Using [pipx](https://pipx.pypa.io/stable/installation/) allows you to install and run Python command-line applications in isolated environments, which helps prevent dependency conflicts with other Python projects.</sub> -->

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

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

❯ uv tool install readmeai
<!-- #### Using `docker` [![docker](https://img.shields.io/badge/Docker-2496ED.svg?style=flat&logo=Docker&logoColor=white)](https://hub.docker.com/r/zeroxeli/readme-ai) -->

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

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

❯ 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

<details><summary>Click to expand instructions</summary>
  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
    
</details><br>

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

🤖 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>
<details closed><summary>Additional Providers (Ollama, Anthropic, Google Gemini)</summary><br> <details closed><summary>Ollama</summary><br>

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
    
</details> <details closed><summary>Anthropic</summary>
  1. Export your Anthropic API key:

    ❯ export ANTHROPIC_API_KEY=<your_api_key>
    
</details> <details closed><summary>Google Gemini</summary>
  1. Export your Google Gemini API key:

    ❯ export GOOGLE_API_KEY=<your_api_key
    
</details> </details>

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

<details closed><summary><i>Click to expand instructions</i></summary>

<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
    
</details>

<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

<!-- #### Using `pytest` [![pytest](https://img.shields.io/badge/Pytest-0A9EDC.svg?style=flat&logo=Pytest&logoColor=white)](https://docs.pytest.org/en/7.1.x/contents.html) -->

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] <sub>Nox is an automation tool that automates testing in multiple Python environments. It is used to ensure compatibility across different Python versions.</sub>


🔡 Configuration

Customize your README generation using these CLI options:

OptionDescriptionDefault
--alignText alignment in headercenter
--apiLLM API service provideroffline
--badge-colorBadge color name or hex code0080ff
--badge-styleBadge icon style typeflat
--header-styleHeader template styleclassic
--toc-styleTable of contents stylebullet
--emojisAdds emojis to the README header sectionsFalse
--imageProject logo imageblue
--modelSpecific LLM model to usegpt-3.5-turbo
--outputOutput filenamereadme-ai.md
--repositoryRepository URL or local directory pathNone
--temperatureCreativity level for content generation0.1
--tree-depthMaximum depth of the directory tree structure2

Run the following command to view all available options:

❯ readmeai --help

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


🎨 Examples

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

TechnologyExample OutputRepositoryDescription
Readme-aireadme-ai.mdreadme-aiReadme-ai project
Apache Flinkreadme-pyflink.mdpyflink-pocPyflink project
Streamlitreadme-streamlit.mdreadme-ai-streamlitStreamlit web app
Vercel & NPMreadme-vercel.mdgithub-readme-quotesVercel deployment
Go & Dockerreadme-docker-go.mddocker-gs-pingDockerized Go app
FastAPI & Redisreadme-fastapi-redis.mdasync-ml-inferenceAsync ML inference service
Javareadme-java.mdMinimal-TodoMinimalist todo Java app
PostgreSQL & DuckDBreadme-postgres.mdBuenavistaPostgres proxy server
Kotlinreadme-kotlin.mdandroid-clientAndroid client app
Offline Modeoffline-mode.mdlitellmLLM API service

<sub>Find additional README examples in the examples directory.</sub>


🏎💨 Roadmap


🔰 Contributing

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

<br> <p align="left"> <a href="https://github.com{/eli64s/readme-ai/}graphs/contributors"> <img src="https://contrib.rocks/image?repo=eli64s/readme-ai"> </a> </p>

🙌 Acknowledgments

<div align="right">

</div>

🎗 License

Copyright © 2023 readme-ai. <br /> Released under the MIT License.

<!-- REFERENCE LINKS --> <!-- README-AI PROJECT --> <!-- INSTALLATION METHODS --> <!-- GIT HOSTS --> <!-- LLM API PROVIDERS --> <!-- EXAMPLE READMEs --> <!-- EXAMPLE REPOSITORIES -->