Generate beautiful README.md files from the terminal, powered by AI.
Project description
README-AI
◦ Generate beautiful and informative README files
◦ Powered by OpenAI's GPT language model APIs
📖 Table of Contents
- 📖 Table of Contents
- 🔭 Overview
- 🎈 Demo
- 🤖 Features
- 👩💻 Usage
- 🛠 Project Roadmap
- 📒 Changelog
- 🤝 Contributing
- 📄 License
- 👏 Acknowledgments
🔭 Overview
🎯 Objective
Dev tool that auto-generates detailed README.md files from the command-line using OpenAI's GPT models. Simply provide a repository URL or 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.
⚠️ Note
This project is under development with an opinionated setup. It's vital to review the text generated by the OpenAI API to ensure it accurately represents your codebase.
🎈 Demo
readmeai CLI
‣ Run readme-ai in your terminal via PyPI, Docker, and more!
🤖 Features
❶ Badges
Project Slogan and 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.
1. Shieldsio flat badge styleCommand: none as its the default style for readme-ai 
|
2. Shieldsio for-the-badge styleCommand: 
|
3. Square iOS style badgesCommand: 
|
❷ Codebase Documentation
Directory Tree and File Summaries |
|
|
‣ Your project's directory structure is visualized using a custom tree function. ‣ Each file in the codebase is summarized by OpenAI's GPT model. |
|
|
|
❸ Features Table
Prompted Text Generation‣ An overview paragraph and features table are generated using detailed prompts, embedded with project metadata. |
|
❹ Dynamic Usage Guides
Installation, Running, and Test‣ 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. |
|
❺ Additional README Sections
|
|
❻ 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! |
AI and ML README Template Concept
|
❼ 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 |
👩💻 Usage
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.
-
Runtime Considerations: README file generation typically takes less than a minute. If the process exceeds a few minutes (e.g., 3 minutes), it's advisable to terminate readme-ai to prevent extended processing times.
📦 Installation
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
⚙️ Configuration
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 |
Styles - flat (default), flat-square, plastic, for-the-badge, social, sqaure |
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! |
Badge Style CLI Options
| --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.
🚀 Running README-AI
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
You can also use the short flags for the CLI options above.
In this example we name the output file readme-ai.md, set the repo URL to readme-ai, use the flat-square badge style, and remove emojis from the README file header names.
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, or without an API key! This option is useful for spinning up a baseline README.md file that still contains your project's metadata.
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.
🧪 Tests
Execute the test suite using the command below.
bash scripts/test.sh
🛠 Project Roadmap
- 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.
📒 Changelog
🤝 Contributing
📄 License
👏 Acknowledgments
Badges
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file readmeai-0.4.35.tar.gz.
File metadata
- Download URL: readmeai-0.4.35.tar.gz
- Upload date:
- Size: 98.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7684dc176e18b1e2a9e954e35c87ac0f9bd991f30afc3dd496ee376547aaf600 |
|
| MD5 | 3356497a702ed4543970700fb21a50f5 |
|
| BLAKE2b-256 | 029e8dc919bd347b5e3e9ee8bd9df91236d4243702fcdc98720be54501f9163d |
File details
Details for the file readmeai-0.4.35-py3-none-any.whl.
File metadata
- Download URL: readmeai-0.4.35-py3-none-any.whl
- Upload date:
- Size: 98.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1389e7279a9be4155ec298a2f00cb290007183b1b7897a479ba9c433954f3592 |
|
| MD5 | df28d517e636c137fd044dbecadab999 |
|
| BLAKE2b-256 | a605953419b0fda62ca855a49b1ef06c6abc7fc4880565796d92b07c3e1e5c75 |
