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
[!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:
Running directly in your browser:
☄️ Features
- 🚀 Automated Documentation: Generate comprehensive README files automatically from your codebase.
- 🎨 Customizable Output: Tailor the styling, formatting, badges, header designs, and more preferences.
- 🤖 Flexible Backends: Seamlessly integrate with
OpenAI
,Ollama
,Anthropic
,Google Gemini
. - 🌐 Language Agnostic: Compatible with a wide range of programming languages and project types.
- 📑 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:
<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
- Python Version:
3.9
or higher - Package Management/Conainter Runtime: Choose one of the following:
Supported Repository Sources
The readmeai
CLI can retrieve source code from the following Git hosting services or your local file system:
Platform | Description | Resource |
---|---|---|
File System | Access repositories on your machine | Learn more |
GitHub | World's largest code hosting platform | GitHub.com |
GitLab | Complete DevOps platform | GitLab.com |
Bitbucket | Atlassian's Git solution | Bitbucket.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:
Provider | Description | Resource |
---|---|---|
OpenAI | Recommended for general use | OpenAI Developer quickstart |
Anthropic | Advanced language models | Anthropic Developer docs |
Google Gemini | Google's multimodal AI model | Gemini API quickstart |
Ollama | Free and open-source (No API key required) | Ollama GitHub repository |
Offline Mode | Run readmeai without a LLM API | Example 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>-
Clone the repository:
❯ git clone https://github.com/eli64s/readme-ai
-
Navigate to the
readme-ai
directory:❯ cd readme-ai
-
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
-
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
-
Install dependencies using Poetry:
❯ poetry install
[!IMPORTANT] To use the Anthropic and Google Gemini clients, extra dependencies are required. Install the package with the following extras:
Anthropic:
❯ pip install "readmeai[anthropic]"
Google Gemini:
❯ pip install "readmeai[google-generativeai]"
Install Multiple Clients:
❯ pip install "readmeai[anthropic,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>
<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:
-
Pull your model of choice from the Ollama repository:
❯ ollama pull mistral:latest
-
Start the Ollama server and set the
OLLAMA_HOST
environment variable:❯ export OLLAMA_HOST=127.0.0.1 && ollama serve
-
Export your Anthropic API key:
❯ export ANTHROPIC_API_KEY=<your_api_key>
-
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
<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:
-
Activate the virtual environment:
❯ conda activate readmeai
-
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
-
Activate the virtual environment:
❯ poetry shell
-
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.
🧪 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:
Option | Description | Default |
---|---|---|
--align | Text alignment 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 |
--header-style | Header template style | classic |
--toc-style | Table of contents style | bullet |
--emojis | Adds emojis to the README header sections | False |
--image | Project logo image | blue |
--model | Specific LLM model to use | gpt-3.5-turbo |
--output | Output filename | readme-ai.md |
--repository | Repository URL or local directory path | None |
--temperature | Creativity level for content generation | 0.1 |
--tree-depth | Maximum depth of the directory tree structure | 2 |
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:
Technology | Example Output | Repository | Description |
---|---|---|---|
Readme-ai | readme-ai.md | readme-ai | Readme-ai project |
Apache Flink | readme-pyflink.md | pyflink-poc | Pyflink project |
Streamlit | readme-streamlit.md | readme-ai-streamlit | Streamlit web app |
Vercel & NPM | readme-vercel.md | github-readme-quotes | Vercel deployment |
Go & Docker | readme-docker-go.md | docker-gs-ping | Dockerized Go app |
FastAPI & Redis | readme-fastapi-redis.md | async-ml-inference | Async ML inference service |
Java | readme-java.md | Minimal-Todo | Minimalist todo Java app |
PostgreSQL & DuckDB | readme-postgres.md | Buenavista | Postgres proxy server |
Kotlin | readme-kotlin.md | android-client | Android client app |
Offline Mode | offline-mode.md | litellm | LLM API service |
<sub>Find additional README examples in the examples directory.</sub>
🏎💨 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.
🙌 Acknowledgments
- Shields.io
- Simple Icons
- Aveek-Saha/GitHub-Profile-Badges
- Ileriayo/Markdown-Badges
- tandpfun/skill-icons
🎗 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 -->