readmeai 0.5.0b2

🎈 Automated README file generator, powered by GPT language model APIs.

README-AI

Automated README file generator, powered by LLM APIs

---

🔗 Quick Links

• 📍 Overview
• 🤖 Demo
• 🔮 Features
• 🚀 Getting Started
• ⚙️ Installation
• 👩‍💻 Running readme-ai
• 🧩 Configuration
• 🛠 Project Roadmap
• 🤝 Contributing

---

📍 Overview

Objective

Readme-ai is a developer tool that auto-generates README.md files using a combination of data extraction and generative ai. Simply provide a repository URL or local path to your codebase and a well-structured and detailed README file will be generated for you.

Motivation

Streamlines documentation creation and maintenance, enhancing developer productivity. This project aims to enable all skill levels, across all domains, to better understand, use, and contribute to open-source software.

[!IMPORTANT]

Readme-ai is currently under development with an opinionated configuration and setup. It is vital to review all text generated by the LLM APIs to ensure it accurately represents your project.

---

🤖 Demo

Standard CLI usage with LLM API key set as an environment variable.

readmeai-cli-demo

You can also generate README files without an API key by using the --offline CLI option.

readmeai-cli-offline-demo

[!TIP]

Offline mode is useful for quickly generating a boilerplate README without incurring API costs. See an offline mode README file here.

---

🔮 Features

Built with flexibility in mind, readme-ai allows users to customize various aspects of the README using CLI options and configuration settings. Content is generated using a combination of data extraction and making a few calls to LLM APIs.

Currently, readme-ai uses generative ai to create four sections of the README file.

i. Header: Project slogan that describes the repository in an engaging way.

ii. Overview: Provides an intro to the project's core use-case and value proposition.

iii. Features: Markdown table containing details about the project's technical components.

iv. Modules: Codebase file summaries are generated and formatted into markdown tables.

All other content is extracted from processing and analyzing repository metadata and files.

Customizable Header

The header section is built using repository metadata and CLI options. Key features include:

• Badges: Svg icons that represent codebase metadata, provided by shields.io and skill-icons.
• Project Logo: Select a project logo image from the base set or provide your image.
• Project Slogan: Catch phrase that describes the project, generated by generative ai.
• Table of Contents/Quick Links: Links to the different sections of the README file.

See a few examples headers generated by readme-ai below.

default output (no options provided to cli)
--align left --badges flat-square --image cloud	--align left --badges flat --image gradient
--badges flat --image custom	--badges skills-light --image grey
--badges flat-square	--badges flat --image black

See the Configuration section below for the complete list of CLI options and settings.

📑 Codebase Documentation

Repository Structure A directory tree structure is generated using pure Python (tree.py) and embedded in the README.

Codebase Summaries Code summaries are generated using LLMs and grouped by directory, displayed in markdown tables.

📍 Overview & Features Table

The overview and features sections are generated using LLM APIs. Structured prompt templates are injected with repository metadata to help produce more accurate and relevant content.

Overview High-level introduction of the project, focused on the value proposition and use-cases, rather than technical aspects.

Features Table Describes technical components of the codebase, including architecture, dependencies, testing, integrations, and more.

🚀 Dynamic Quickstart Guides

Getting Started or Quick Start Generates structured guides for installing, running, and testing your project. These steps are created by identifying dependencies and languages used in the codebase, and mapping this data to configuration files such as the language_setup.toml file.

🤝 Contributing Guidelines & More

Additional Sections The remaining README sections are built from a baseline template that includes common sections such as Project Roadmap, Contributing Guidelines, License, and Acknowledgements.

Contributing Guidelines The contributing guidelines has a dropdown that outlines a general process for contributing to your project.

🧩 Template READMEs

This feature is currently under development. The template system will allow users to generate README files in different flavors, such as ai, data, web development, etc.

README Template for ML & Data Overview: Project objectives, scope, outcomes. Project Structure: Organization and components. Data Preprocessing: Data sources and methods. Feature Engineering: Impact on model performance. Model Architecture: Selection and development strategies. Training: Procedures, tuning, strategies. Testing and Evaluation: Results, analysis, benchmarks. Deployment: System integration, APIs. Usage and Maintenance: User guide, model upkeep. Results and Discussion: Implications, future work. Ethical Considerations: Ethics, privacy, fairness. Contributing: Contribution guidelines. Acknowledgements: Credits, resources used. License: Usage rights, restrictions.

Example READMEs

Explore example README.md files generated by readme-ai below.

⭑	Output File 📄	Input Repository 📁	Repository Type 🔢
⭑	readme-python.md	readme-ai	Python
⭑	readme-typescript.md	chatgpt-app-react-ts	TypeScript, React
⭑	readme-postgres.md	postgres-proxy-server	Postgres, Duckdb
⭑	readme-kotlin.md	file.io-android-client	Kotlin, Android
⭑	readme-streamlit.md	readme-ai-streamlit	Python, Streamlit
⭑	readme-rust-c.md	rust-c-app	C, Rust
⭑	readme-go.md	go-docker-app	Go
⭑	readme-java.md	java-minimal-todo	Java
⭑	readme-fastapi-redis.md	async-ml-inference	FastAPI, Redis
⭑	readme-mlops.md	mlops-course	Python, Jupyter
⭑	readme-pyflink.md	flink-flow	PyFlink
⭑	readme-gitlab.md	gitlab	GitLab
⭑	readme-bitbucket.md	bitbucket	BitBucket
⭑	readme-local.md	filesystem	Filesystem

---

🚀 Getting Started

Requirements

• Python: 3.9+
• Package manager or container runtime: pip or docker recommended.
• LLM API key: currently OpenAI and Google Cloud are supported.

Repository

A repository URL or local path to your codebase is required run readme-ai. The following are supported:

• GitHub
• GitLab
• Bitbucket
• File System

OpenAI API Key

An OpenAI API account and API key are needed to use readme-ai. Get started by creating an account here. Once you have an account, you can create an API key on the API settings page.

[!WARNING]

Before using readme-ai, its essential to understand the potential risks and costs associated with using AI-powered tools.

• Review Sensitive Information: Ensure all content in your repository is free of sensitive information before running the tool. This project does not remove sensitive data from your codebase, nor from the output README file.

• API Usage Costs: The OpenAI API is not free and costs can accumulate quickly! You will be charged for each request made by readme-ai. Be sure to monitor API usage costs using the OpenAI API Usage Dashboard.

---

⚙️ Installation

Using pip

pip install readmeai

Using docker

docker pull zeroxeli/readme-ai:latest

Using conda

conda install -c conda-forge readmeai

Alternatively, clone the readme-ai repository and build from source.

git clone https://github.com/eli64s/readme-ai

Change into the project directory.

cd readme-ai

And install the dependencies using one of the methods below.

Using bash

bash setup/setup.sh

Using pipenv

pipenv install && \
pipenv shell

Using poetry

poetry install && \
poetry shell

---

👩‍💻 Running readme-ai

Before running the CLI, ensure you export your OpenAI API key as an environment variable.

On Linux or MacOS

$ export OPENAI_API_KEY=YOUR_API_KEY

On Windows

$ set OPENAI_API_KEY=YOUR_API_KEY

Use one of the methods below to run the application (Pip, Docker, Conda, Streamlit, etc).

Using pip

readmeai --repository https://github.com/eli64s/readme-ai

Using docker

docker run -it \
-e OPENAI_API_KEY=$OPENAI_API_KEY \
-v "$(pwd)":/app zeroxeli/readme-ai:latest \
-r https://github.com/eli64s/readme-ai

Using conda

readmeai -r https://github.com/eli64s/readme-ai

Using streamlit

Try readme-ai directly in your browser with Streamlit, no installation required! See readme-ai-streamlit for more details.

From source

Using bash

conda activate readmeai && \
python3 -m readmeai.cli.commands -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

---

🧪 Tests

Use pytest to run the default test suite.

make pytest

Use nox to run the test suite against multiple Python versions including (3.9, 3.10, 3.11, 3.12).

nox -f noxfile.py

---

🧩 Configuration

Run the readmeai command in your terminal with the following options to tailor your README file.

Command-Line Options

Option	Description	Values	Default Value	Data Type
-a, --align	Align the text in the README.md file's header.	center, left	center	String
--api-key	LLM API key to generate text for the README.md file.			String
-b, --badges	Badge icon style types for README.md badges.	default, flat, flat-square, for-the-badge, plastic, skills, skills-light, social	default	String
-e, --emojis	Adds emojis to the README.md file's header sections.		False	Boolean
-i, --image	Project logo image displayed in the README file header.	CUSTOM, DEFAULT, BLACK, GRADIENT, GREY, PURPLE, YELLOW, CLOUD	DEFAULT	String
🚧 --language	Language for generating the README.md file.		en	String
--max-tokens	Maximum number of tokens for each section of the README.md file.			Integer
-m, --model	GPT language model for generating various sections of the README.md file.			String
--offline	Generates a README.md file without API calls, with placeholders for generated content.		False	Boolean
-o, --output	Output file name for the README file.		readme-ai.md	String
-r, --repository	Remote repository URL or local directory path for the project.			String
-t, --temperature	Sets the creativity level for content generation.	0.0 to 2.0	1.0	Float
🚧 --template	README template file for generating the README.md file.			String
--vertex_ai	Google Vertex AI configuration, requires location and project ID.			Tuple (String)
--help	Displays help information about the command and its options.

_{🚧 = feature currently under development.
For additional command-line information, run readmeai --help in your terminal for more details about each option.}

Badge Icons

Select your preferred badge icon style to display in your output file using the --badges flag. The default badge style displays basic metadata about your repository using shields.io badges. If you select another option, the default badges will be automatically included.

Options	Preview
default
flat
flat-square
for-the-badge
plastic
skills
skills-light
social

Project Logo

Select an image to display in your README header section using the --image flag.

Options	Preview
default
black
gradient
grey
purple
yellow
cloud

To provide your own image, use the CLI option --image custom and you will be prompted to enter a URL to your image.

Pydantic Models and Settings

For more details about the configuration settings, see the project documentation or jump right into the settings file.

Return

---

🛠 Project Roadmap

• Publish readme-ai CLI as a Python package on PyPI.
  • PyPI Package
• Containerize the readme-ai CLI as a Docker image via Docker Hub.
  • Docker Hub Image
• Serve the readme-ai CLI as a web app, deployed on Streamlit Community Cloud.
  • Streamlit Web Application
• Integrate singular interface for all LLM API providers (Anthropic, Cohere, Gemini, etc.)
• Design template system to give users a variety of README document flavors (ai, data, web, etc.)
• Develop robust documentation generation process to extend to full project docs (i.e. Sphinx, MkDocs, etc.)
• Add support for generating README files in any language (i.e. CN, ES, FR, JA, KO, RU).
• Create GitHub Actions script to automatically update README file content on repository push.

---

📒 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

---