๐ Generate beautiful README.md files. Powered by OpenAI's GPT language model APIs ๐ซ
Project description
README-AI
โฆ Generate beautiful and informative README.md files.
โฆ Developed with OpenAI's GPT language model APIs.
๐ Table of Contents
- ๐ Table of Contents
- ๐ Overview
- ๐ค Demo
- ๐น Play
- โจ Features
- ๐ Getting Started
- ๐ฃ Roadmap
- ๐ Changelog
- ๐ค Contributing
- ๐ License
- ๐ Acknowledgments
๐ Overview
README-AI is a powerful command-line tool that generates robust README.md files for your software and data projects. By simply providing a remote repository URL or path to your codebase, this tool auto-generates documentation for your entire project, leveraging the capabilities OpenAI's GPT language model APIs. README-AI is currently available as a Python library and Docker image.
๐ฏ Motivation
README-AI simplifies the process of writing and maintaining high-quality project documentation, enhancing developer productivity and workflow. The ultimate goal of readme-ai is to improve the adoption and usability of open-source software, enabling all skill levels to better understand complex codebases and easily use open-source tools.
โ ๏ธ Disclaimer
This project is currently under development and has an opinionated configuration. While readme-ai provides an excellent starting point for documentation, its important to review all text generated by the OpenAI API to ensure it accurately represents your codebase.
๐ค Demo
๐น Play
Explore readme-ai in directly in browser with Streamlit Community Cloud. No installation required!
โจ Features
1.
๐
๐ Codebase Documentation
โฆ Repository File Summaries
|
โ
๐
๐ Badges
โฆ Introduction, Badges, & Table of Contents
|
โ
๐
๐ง Prompted Text Generation
โฆ Features Table & Overview
|
โ
๐
๐ฒ Repository Tree
โ
๐
๐ฆ Dynamic User Setup Guides
โฆ Installation, Usage, & Testing
|
โ
๐
๐ฉโ๐ป Contributing Guidelines & more!
โ
๐
๐ฅ Example README Files
Example markdown files generated by readme-ai!
Example File | Repository | Language | Bytes | |
---|---|---|---|---|
1๏ธโฃ | readme-python.md | readme-ai | Python | 19,839 |
2๏ธโฃ | readme-typescript.md | chatgpt-app-react-typescript | TypeScript, React | 988 |
3๏ธโฃ | readme-javascript.md | assistant-chat-gpt-javascript | JavaScript, React | 212 |
4๏ธโฃ | readme-kotlin.md | file.io-android-client | Kotlin, Java, Android | 113,649 |
5๏ธโฃ | readme-rust-c.md | rust-c-app | C, Rust | 72 |
6๏ธโฃ | readme-go.md | go-docker-app | Go | 41 |
7๏ธโฃ | readme-java.md | java-minimal-todo | Java | 17,725 |
8๏ธโฃ | readme-fastapi-redis.md | async-ml-inference | Python, FastAPI, Redis | 355 |
9๏ธโฃ | readme-mlops.md | mlops-course | Python, Jupyter | 8,524 |
๐ | readme-pyflink.md | flink-flow | PyFlink | 32 |
โ
๐
๐ Custom README templates coming soon!
Developing a feature that allows users to select from a variety of README formats and styles.
Custom templates will be tailored for use-cases such as data, ai & ml, research, minimal, and more!
๐ 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 path to your local project's directory is needed to use readme-ai. The following repository types are currently supported:
- GitHub
- GitLab
- 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 - User Guide
- 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 - Important Notes
- Ensure all content in your repository is free of sensitive information before executing readme-ai.
- The OpenAI API is NOT free and you will be charged for each request made, which can accumulate costs rapidly.
- Regularly monitor your API usage and costs by visiting the OpenAI API Usage Dashboard.
- Also ensure your OpenAI account has sufficient credits to run the readme-ai application.
- Setting up an OpenAI API payment account is recommended to avoid API usage restrictions.
- Without a payment method, API usage will be restricted to the base gpt-3 models.
- This often leads to inaccurate README file generation and errors due to API request limits.
- README file generation should take under 1 minute. Terminate readme-ai if runtime exceeds more than a few minutes (i.e. 3 minutes).
๐ฆ Install
Using Pip
Pip is the recommended installation method for most users. More details about the Python package can be found on PyPI.
pip install --upgrade readmeai
Using Docker
Docker is recommended for users wanting to run readme-ai in a containerized environment. More details about the image can be found on Docker Hub.
docker pull zeroxeli/readme-ai:latest
Install Manually
1๏ธโฃ Clone the readme-ai repository.
git clone https://github.com/eli64s/readme-ai
2๏ธโฃ Navigate to readme-ai directory.
cd readme-ai
3๏ธโฃ Install dependencies using a method below.
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 install
๐ฎ Usage
๐ก Command-Line Arguments
To generate a README.md file, use the readmeai
command in your terminal, along with the arguments below.
Short Flag | Long Flag | Description | Status |
---|---|---|---|
-k |
--api-key |
Your OpenAI API key. | Required |
-o |
--output |
The output path for your README.md file. | Required |
-r |
--repository |
The URL or path to your code repository. | Required |
-t |
--template |
The README template format to use. (coming soon!) | Coming Soon! |
-l |
--language |
The language of text written in the README file. | Coming Soon! |
๐ Configuration
To customize the README file generation process, you can modify the configuration file. The file contains the following sections:
- api - OpenAI language model API configuration settings.
- 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.
๐ Streamlit Community Cloud
You can directly use readme-ai in your browser without installing anything!
๐ช Running README-AI
Using Pip
# Option 1: Run readmeai command with all required command-line arguments.
readmeai --api-key "YOUR_API_KEY" --output readme-ai.md --repository https://github.com/eli64s/readme-ai
# Option 2: Run readmeai command with OpenAI API key set as environment variable.
export OPENAI_API_KEY="YOUR_API_KEY"
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai
Using Docker
# Option 1: Run Docker container with all required command-line arguments.
docker run -it \
-e OPENAI_API_KEY="YOUR_API_KEY" \
-v "$(pwd)":/app zeroxeli/readme-ai:latest \
readmeai -o readme-ai.md -r https://github.com/eli64s/readme-ai
# Option 2: Run Docker container with OpenAI API key set as environment variable.
export OPENAI_API_KEY="YOUR_API_KEY"
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
Run Manually
Using Conda
conda activate readmeai
export OPENAI_API_KEY="YOUR_API_KEY"
python readmeai/main.py -o readme-ai.md -r https://github.com/eli64s/readme-ai
Using Poetry
poetry shell
export OPENAI_API_KEY="YOUR_API_KEY"
poetry run python readmeai/main.py -o readme-ai.md -r https://github.com/eli64s/readme-ai
๐งช Running Tests
Execute the test suite using command below.
bash scripts/test.sh
๐ฃ Roadmap
- Publish project as a Python library via PyPI and a Docker image on Docker Hub.
- Integrate and deploy app with Streamlit to provide a simple user-interface for using the tool.
- Develop GitHub Actions script to automatically update the README file when new code is pushed.
- Design README output templates for a variety of use-cases (i.e. data, web-dev, minimal, etc.)
- Add support for generating README files in any language (i.e. CN, ES, FR, JA, KO, RU).
๐ Changelog
๐ค Contributing
๐ License
๐ Acknowledgments
Badges
Project details
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
Hashes for readmeai-0.3.34-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ab56126ac5f069e52ba04491d9054ce4776f383892e9e9843195038efdfaa5e3 |
|
MD5 | c1eb5ca90fc40c07bbd3a69a42ae8bba |
|
BLAKE2b-256 | 89b980be4ceed861e281cdafe6ca75e0df4b7fe6ae655e21f4f947d6ea70c5c3 |