readmeai 0.4.68

🚀 Generate beautiful README files from the terminal, powered by OpenAI's GPT language models 💫

README-AI

Automatically generate beautiful README files using OpenAI's GPT language models.

---

🔗 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.

[!IMPORTANT]

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-cli-demo

• 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-cli-offline-demo

---

🤖 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	(repository deleted)	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

1. Go to the OpenAI website.
2. Click the "Sign up for free" button.
3. Fill out the registration form with your information and agree to the terms of service.
4. Once logged in, click on the "API" tab.
5. Follow the instructions to create a new API key.
6. Copy the API key and keep it in a secure place.

⚠️ OpenAI API - Cautionary Guidelines

1. 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.

2. 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.

3. 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

Then use one of the methods below to install the project's dependencies (Bash, Conda, Pipenv, or Poetry).

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 pipenv

pipenv install && \
pipenv shell

Using poetry

poetry install && \
poetry shell

---

⚙️ 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-4 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 pipenv

pipenv shell && \
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

Try readme-ai in your browser, no installation required!

[!NOTE]

Hosted on Streamlit's Community Cloud. It may be unstable or unavailable at times.

Not as feature-rich as the CLI, but it's a great way to get started with readme-ai.

For more details about the Streamlit app, see the readmeai-ui repository.

---

🧪 Tests

Execute the following command to run the test suite.

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

Changelog

---

🤝 Contributing

• Discussions
• Open an Issue
• Contributing Guidelines

---

📄 License

MIT

---

👏 Acknowledgments

Badges

• Shields.io
• Aveek-Saha/GitHub-Profile-Badges
• Ileriayo/Markdown-Badges
• tandpfun/skill-icons

Return

---