Automatically generate beautiful README files powered by AI
Objective
README-AI is a dev tool that auto-generates detailed README.md files from the command-line using OpenAI's GPT models. Provide a repository URL or local directory path, and README-AI builds a well-structured README.md for your project.
Motivation
Streamlines documentation creation and maintenance, enhancing developer productivity. README-AI aims to improve the adoption of open-source software, enabling all skill levels and disciplines to understand, utilize, and contribute to projects more effectively.
Warning
This project is under development with an opinionated setup. It is vital to review the text generated by the OpenAI API to ensure it accurately represents your codebase.
Run readme-ai in your terminal via PyPI, Docker, and more.
readmeai-demo.mov
- CLI option
--offline
can be used to generate a README.md without an OpenAI API key. - Useful for quickly getting a baseline document containg your project's metadata!
readmeai-offline-demo.mov
❶ Badges
‣ A slogan to highlight your poject is generated by prompting OpenAI's GPT engine. ‣ Codebase dependencies and metadata are visualized using Shields.io badges. |
![]() |
‣ Use the CLI option --badges
to select the style of badges for your README!
‣ 6 options currently supported: flat (default), flat-square, plastic, for-the-badge, social, square. Find a few examples below.
Command: none as its the default style for readme-ai |
Command: |
Command: |
❸ Features Table
‣ An overview paragraph and features table are generated using detailed prompts, embedded with project metadata. |
![]() |
❹ Dynamic Usage Guides
‣ Generates instructions for installing, running, and testing your project. Instructions are created by identifying the codebase's top language and referring to our language_setup.toml configuration file. |
![]() |
❻ Templates (coming soon)
‣ Developing CLI option letting users select from a variety of README styles ‣ Templates for use-cases such as data, machine learning, web development, and more! |
|
❼ Example README Files
Output File | Repository | Languages | |
---|---|---|---|
1️⃣ | readme-python.md | readme-ai | Python |
2️⃣ | readme-typescript.md | chatgpt-app-react-typescript | TypeScript, React |
3️⃣ | readme-javascript.md | assistant-chat-gpt-javascript | JavaScript, React |
4️⃣ | readme-kotlin.md | file.io-android-client | Kotlin, Java, Android |
5️⃣ | readme-rust-c.md | rust-c-app | C, Rust |
6️⃣ | readme-go.md | go-docker-app | Go |
7️⃣ | readme-java.md | java-minimal-todo | Java |
8️⃣ | readme-fastapi-redis.md | async-ml-inference | Python, FastAPI, Redis |
9️⃣ | readme-mlops.md | mlops-course | Python, Jupyter |
🔟 | readme-pyflink.md | flink-flow | PyFlink |
Dependencies
Please ensure you have the following dependencies installed on your system:
- Python version 3.9 or higher
- Package manager (i.e. pip, conda, poetry) or Docker
- OpenAI API paid account and API key
Repository
A remote repository URL or local directory path to your project is needed to use readme-ai. The following platforms are currently supported:
- GitHub
- GitLab
- Bitbucket
- File System
OpenAI API
An OpenAI API account and API key are needed to use readme-ai. The steps below outline this process:
🔐 OpenAI API - Setup Instructions
- Go to the OpenAI website.
- Click the "Sign up for free" button.
- Fill out the registration form with your information and agree to the terms of service.
- Once logged in, click on the "API" tab.
- Follow the instructions to create a new API key.
- Copy the API key and keep it in a secure place.
⚠️ OpenAI API - Cautionary Guidelines
-
Review Sensitive Information: Before running the application, ensure that all content in your repository is free of sensitive information. Please note that readme-ai does not filter out sensitive data from the README file, and it does not modify any files in your repository.
-
API Usage Costs: The OpenAI API is not free, and you will be charged for each request made. Costs can accumulate rapidly, so it's essential to be aware of your usage. You can monitor your API usage and associated costs by visiting the OpenAI API Usage Dashboard.
-
Paid Account Recommended: Setting up a paid account with OpenAI is highly recommended to avoid potential issues. Without a payment method on file, your API usage will be restricted to base GPT-3 models. This limitation can result in less accurate README file generation and may lead to API errors due to request limits.
Using pip
pip install readmeai
Using docker
docker pull zeroxeli/readme-ai:latest
Alternatively, clone the readme-ai repository and build from source:
git clone https://github.com/eli64s/readme-ai
cd readme-ai
Using bash
bash setup/setup.sh
Using conda
conda create -n readmeai python=3.9 -y && \
conda activate readmeai && \
pip install -r requirements.txt
Using poetry
poetry shell && \
poetry install
To generate a README.md file, use the readmeai
command in your terminal, along with the arguments below.
Short Flag | Long Flag | Description | Type | Status |
---|---|---|---|---|
-k |
--api-key |
Your language model API secret key. | String | Optional |
-b |
--badges |
Badge style options for output file. See below for more details | String | Optional |
-e |
--emojis |
Use false to remove emojis from README default template. |
Boolean | Optional |
-f |
--offline |
Use true to run README-AI without an API key. |
Boolean | Optional |
-m |
--model |
Default large language model is the gpt-3.5-turbo engine. |
String | Optional |
-o |
--output |
The output path for your README.md file. | Path/String | Optional |
-r |
--repository |
The URL or path to your code repository. | URL/String | Required |
-t |
--temperature |
The temperature (randomness) of the model responses. | Float | Optional |
-l |
--language |
The language of text to write README in. | String | Coming Soon! |
-s |
--style |
The README template style to build. | String | Coming Soon! |
--badges | svg icon |
---|---|
flat-square |
|
plastic |
|
for-the-badge |
|
social |
|
flat |
|
apps |
|
apps-light |
|
Custom Settings
To customize the README file generation process, you can modify the project's configuration file:
- api: OpenAI language model API configuration settings.
- base_urls: Base URLs for supported remote repository platforms.
- cli: CLI option settings used by the readme-ai application.
- git: Default git repository settings used if no repository is provided.
- paths: Directory paths and files used by the readme-ai application.
- prompts: Large language model prompts used to generate the README file.
- md: Dynamic Markdown section code templates used to build the README file.
First, add your OpenAI API key to environment variables.
On Linux/MacOS
export OPENAI_API_KEY=YOUR_API_KEY
On Windows
set OPENAI_API_KEY=YOUR_API_KEY
Next, use one of the methods below to run the application.
Using pip
readmeai --output readme-ai.md --repository https://github.com/eli64s/readme-ai
Below we use short flags
in the command, setting badge style to -b flat-square
, and removing emojis -e false
from the output file.
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai -b flat-square -e false
Additionally, you can run readme-ai in offline mode without an API key.
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai --offline true
Offline mode example README.md
Using docker
docker run -it \
-e OPENAI_API_KEY=$OPENAI_API_KEY \
-v "$(pwd)":/app zeroxeli/readme-ai:latest \
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai
Using Conda
conda activate readmeai
python3 -m readmeai.cli.commands -o readme-ai.md -r https://github.com/eli64s/readme-ai
Using Poetry
poetry shell
poetry run python3 -m readmeai.cli.commands -o readme-ai.md -r https://github.com/eli64s/readme-ai
Using Streamlit
Generate a README files directly in your browser on Streamlit Cloud!
🎈 Navigate at readmeai.streamlit.app
Application may be unavailable at times as it's hosted on a free tier.
Execute the test suite using the command below.
bash scripts/test.sh
- Publish project as a Python library via PyPI for easy installation.
- Make project available as a Docker image on Docker Hub.
- Integrate and deploy app with Streamlit to make tool more widely accessible.
- Refactor our large language model engine to enable more robust README generation.
- Explore LangChain 🦜️🔗 as an alternative to using the OpenAI API directly.
- Explore LlamaIndex 🦙 framework and Retrieval Augmented Generation (RAG) paradigm.
- Building template system to create README files for specific use-cases (data, mobile, web, etc.)
- Add support for generating README files in any language (i.e. CN, ES, FR, JA, KO, RU).
- Develop GitHub Actions script to automatically update the README file when new code is pushed.
Badges