๐ 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
- ๐ค Demos
- ๐ซ 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.
๐ค Demos
โก๏ธ Local Environment
โ Streamlit Community Cloud
|
๐ซ 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.
๐ช Running README-AI
Using Streamlit
Use the app directly in your browser via Streamlit Community Cloud.
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.36-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6fd7f8c09d5e5daee0d51b9368bfa43c7c886c9c5b4f3640a8f978dd945c25e3 |
|
MD5 | 2cf2ff036aa519854b34b2f090e42819 |
|
BLAKE2b-256 | 0a4be6dd7b9f6964f46c8519ecbcaf3ac140f64d44ffd68de0c73f0eb02936f8 |