README-AI

Automatically generate beautiful README files powered by AI

Quick Links

Overview
Demo
Features
Getting Started
Project Roadmap
Contributing
License

Overview

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.

Demo

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

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 style

Command: none as its the default style for readme-ai

2. Shieldsio for-the-badge style

Command: --badges for-the-badge

3. Square iOS style badges

Command: --badges square

❷ 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

Overview: Summary of the projects' objectives, scope, and expected outcomes.
Project Structure: Overview of the organization of the projects and their main components.
Data Preprocessing: Data sources, collection methods, and types of data
Feature Engineering: Importance of feature engineering and its impact on model performance.
Model Architecture and Development: Model selection, dev strategies, and implemented algorithms.
Training and Validation: Info on model training procedures, hyperparameter tuning, and validation strategies.
Testing and Evaluation: Model testing results, performance analysis, and comparison with benchmarks.
Deployment and Integration: Integration with other systems, APIs, and user interfaces
Usage and Maintenance: User guide on how to use the deployed models and interfaces.
Results and Discussion: Implications, limitations, and future work.
Ethical Considerations: Ethical aspects, data privacy, and fairness in model predictions.
Contributing: Procedures for submitting contributions, reporting issues, and proposing enhancements.
Acknowledgements: References to resources, libraries, and frameworks used.
License: Explanation of usage rights, restrictions, and attribution requirements.

❼ 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

Return

Getting Started

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.

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`	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!

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

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.

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.
- PyPI - readmeai
Make project available as a Docker image on Docker Hub.
- Docker Hub - readme-ai
Integrate and deploy app with Streamlit to make tool more widely accessible.
- Streamlit Community Cloud - readmeai
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

MIT

Acknowledgments

Badges