Automated README file generator, powered by LLM APIs

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.

Standard CLI usage, providing a repository URL to generate a README file.

Generate a README file without making API calls using the --api offline CLI option.

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

Currently, four sections of the README file are generated using LLMs:

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.

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

Requirements

• Python: 3.9+
• Package manager or container runtime: pip or docker recommended.
• LLM API: OpenAI and Google Vertex AI LLM APIs are currently 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.

pip install readmeai

docker pull zeroxeli/readme-ai:latest

conda install -c conda-forge readmeai

Set your OpenAI API key as an environment variable.

# Using Linux or macOS
$ export OPENAI_API_KEY=<your_api_key>

# Using Windows
$ set OPENAI_API=<your_api_key>

Set your Google Cloud project ID and location as environment variables.

$ export VERTEXAI_LOCATION=<your_location>
$ export VERTEXAI_PROJECT=<your_project>

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

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

_{Try directly in your browser on Streamlit, no installation required! For more details, check out the readme-ai-streamlit repository.}

$ make pytest

$ nox -f noxfile.py

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

_{🚧 feature currently under development}

The --badges option lets you select the style of the default badge set.

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

When providing the --badges option, readme-ai does two things:

1. Formats the default badge set to match the selection (i.e. flat, flat-square, etc.).
2. Generates an additional badge set representing your projects dependencies and tech stack (i.e. Python, Docker, etc.)

$ readmeai --badges flat-square --repository https://github.com/eli64s/readme-ai

{... project logo ...}

{... project name ...}

{...project slogan...}

Developed with the software and tools below.

{... end of header ...}

Select a project logo using the --image option. The following options are available:

blue	gradient	black
cloud	purple	grey

For custom images, see the following options:

• Use --image file option to invoke a prompt to upload a custom image file.
• Use --image url option to invoke a prompt to enter a custom image URL.
• Use --image llm option to generate a logo using an LLM API (in development).

• Add new CLI options to enhance README file customization.
  • --api Integrate singular interface for all LLM APIs (OpenAI, Google Cloud, etc.)
  • --audit to review existing README files and suggest improvements.
  • --template to select a README template style (i.e. ai, data, web, etc.)
  • --language to generate README files in any language (i.e. zh-CN, ES, FR, JA, KO, RU)
• Develop robust documentation generator to build full project docs (i.e. Sphinx, MkDocs)
• Create community-driven templates for README files and gallery of readme-ai examples.
• GitHub Actions script to automatically update README file content on repository push.

Changelog

• Discussions
• Open an Issue
• Contributing Guidelines

MIT

Badges

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

Return