README-AI

Automated README file generator, powered by large language model APIs

Table of Contents

📍 Overview
👾 Demo
🧩 Features
🗂️ Examples
🚀 Getting Started
📦 Configuration
🔭 Roadmap
🧑‍💻 Contributing
🎗 License

📍 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 generated text from the LLM API to ensure it accurately represents your project.}

👾 Demo

Standard CLI Usage:

readmeai-cli-demo.mov

Offline Mode Demonstration:

readmeai-streamlit-demo.mov

Tip

_{Offline mode is useful for generating a boilerplate README at no cost. View the offline README.md example here!}

🧩 Features

Flexible README Generation

Readme-ai uses a balanced approach to building README files, combining data extraction and generative AI to create comprehensive and informative documentation.

Data Extraction & Analysis: File parsers and analyzers are used to extract project metadata, dependencies, and other relevant details. This data is used to both populate many sections of the README, as well as provide context to the LLM API.
Generative Content: For more abstract or creative sections, readme-ai uses LLM APIs to generate content that is both informative and engaging. This includes sections such as a project slogan, overview, features table, and file summaries.

CLI Customization

Over a dozen CLI options are available to customize the README generation process:

LLM Options: Run the tool with OpenAI, Ollama, Google Gemini, or in offline mode.
Offline Mode: Generate a README without making API calls. Readme-ai is still able to populate a significant portion of the README using metadata collected during preprocessing.
Project Badges: Choose from an array of badge styles, colors, and alignments.
Project Logo: Select from the default set, upload your own, or let the LLM give it a try!

A few examples of the CLI options in action:

`default output (no options provided to cli)`
`--alignment left --badge-style flat-square --image cloud`	`--alignment left --badge-style flat --image gradient`
`--badge-style flat --image custom`	`--badge-style skills-light --image grey`
`--badge-style flat-square`	`--badge-style flat --image black`

See the Configuration section for a complete list of CLI options.

👋 Overview

Overview

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

🧩 Features

Features Table

prompt template.

📄 Codebase Documentation

Repository Structure

(tree.py)

File Summaries

prompts!

🚀 Quickstart Commands

Getting Started

language

dependency

Install

Usage

Test

parsers

🔰 Contributing Guidelines

Contributing Guide

- Dropdown section that outlines general process for contributing to your project.

- Provides links to your contributing guidelines, issues page, and more resources.

- Graph of contributors is also included.

Additional Sections

Project Roadmap

Contributing Guidelines

License

Acknowledgements

🎨 Templates (wip)

README Template for ML & Data

- Themed templates tailored to AI, web, data science projects.

- Sections targetted to programming domain.

- Framework for consistent, comprehensive READMEs

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.

🗂️ Examples

	Output File	Input Repository	Input Contents
▹	readme-python.md	readme-ai	Python
▹	readme-google-gemini.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-local.md	Local Directory	Flink, Python

🚀 Getting Started

System Requirements:

Python 3.9+
Package manager/Container: pip, pipx, docker
LLM service: OpenAI, Ollama, Google Gemini, Offline Mode

Repository URL or Local Path:

Make sure to have a repository URL or local directory path ready for the CLI.

Choosing an LLM Service:

OpenAI: Recommended, requires an account setup and API key.
Ollama: Free and open-source, potentially slower and more resource-intensive.
Google Gemini: Requires a Google Cloud account and API key.
Offline Mode: Generates a boilerplate README without making API calls.

⚙️ Installation

Using `pip`

pip install readmeai

Tip

_{Use pipx to install and run Python command-line applications without causing dependency conflicts with other packages!}

Using `docker`

docker pull zeroxeli/readme-ai:latest

Using `conda`

conda install -c conda-forge readmeai

From `source`

Clone and Install

Clone repository and change directory.
$ git clone https://github.com/eli64s/readme-ai
$ cd readme-ai

Using `bash`

$ bash setup/setup.sh

Using `poetry`

$ poetry install

_{Similiary you can use pipenv or pip to install the requirements.txt.}

🤖 Usage

Environment Variables

Using `OpenAI`

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_KEY=<your_api_key>

Using `Ollama`

Set Ollama local host as an environment variable.
$ export OLLAMA_HOST=127.0.0.1
$ ollama pull mistral:latest    # llama2, etc.
$ ollama serve                  # run if not using the Ollama desktop app
_{For more details, check out the Ollama repository.}

Using `Google Gemini`

Set your Google Cloud project ID and location as environment variables.
$ export GOOGLE_API_KEY=<your_api_key>

Run the CLI

Using `pip`

# Using OpenAI API
readmeai --repository https://github.com/eli64s/readme-ai --api openai

# Using Ollama local model
readmeai --repository https://github.com/eli64s/readme-ai --api ollama --model mistral

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 `streamlit`

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

From `source`

Usage

Using `bash`

$ conda activate readmeai
$ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai

Using `poetry`

$ poetry shell
$ poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai

🧪 Tests

Using `pytest`

$ make pytest

Using `nox`

$ nox -f noxfile.py

Tip

_{Use nox to test application against multiple Python environments and dependencies!}

📦 Configuration

Customize the README file using the CLI options below.

Option	Type	Description	Default Value
`--alignment`, `-a`	String	Align the text in the README.md file's header.	`center`
`--api`	String	LLM API service to use for text generation.	`offline`
`--badge-color`	String	Badge color name or hex code.	`0080ff`
`--badge-style`	String	Badge icon style type.	see below
`--base-url`	String	Base URL for the repository.	`v1/chat/completions`
`--context-window`	Integer	Maximum context window of the LLM API.	`3999`
`--emojis`, `-e`	Boolean	Adds emojis to the README.md file's header sections.	`False`
`--image`, `-i`	String	Project logo image displayed in the README file header.	`blue`
`🚧 --language`	String	Language for generating the README.md file.	`en`
`--model`, `-m`	String	LLM API to use for text generation.	`gpt-3.5-turbo`
`--output`, `-o`	String	Output file name for the README file.	`readme-ai.md`
`--rate-limit`	Integer	Maximum number of API requests per minute.	`5`
`--repository`, `-r`	String	Repository URL or local directory path.	`None`
`--temperature`, `-t`	Float	Sets the creativity level for content generation.	`0.9`
`🚧 --template`	String	README template style.	`default`
`--top-p`	Float	Sets the probability of the top-p sampling method.	`0.9`
`--tree-depth`	Integer	Maximum depth of the directory tree structure.	`2`
`--help`		Displays help information about the command and its options.

_{🚧 feature under development}

Badge Customization

The --badge-style 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 --badge-style option, readme-ai does two things:

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

Example

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

Output

{... project logo ...}

{... project name ...}

{...project slogan...}

Developed with the software and tools below.

{... end of header ...}

Project Logo

Select a project logo using the --image option.

blue	gradient	black

cloud	purple	grey

For custom images, see the following options:

Use --image custom to invoke a prompt to upload a local image file path or URL.
Use --image llm to generate a project logo using a LLM API (OpenAI only).

🔭 Roadmap

Add new CLI options to enhance README file customization.
- --api Integrate singular interface for all LLM APIs (OpenAI, Ollama, Gemini, 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

Changelog

🧑‍💻 Contributing

To grow the project, we need your help! See the links below to get started.

🎗 License

MIT

👊 Acknowledgments

Return

Name		Name	Last commit message	Last commit date
Latest commit History 660 Commits
.github		.github
docs		docs
examples		examples
readmeai		readmeai
scripts		scripts
setup		setup
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
mkdocs.yml		mkdocs.yml
noxfile.py		noxfile.py
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

License

WannabeTechWarrior/readme-ai

Folders and files

Latest commit

History

Repository files navigation

README-AI

📍 Overview

👾 Demo

🧩 Features

Flexible README Generation

CLI Customization

🗂️ Examples

🚀 Getting Started

⚙️ Installation

Using pip

Using docker

Using conda

From source

Using bash

Using poetry

🤖 Usage

Using OpenAI

Using Ollama

Using Google Gemini

Using pip

Using docker

Using streamlit

From source

Using bash

Using poetry

🧪 Tests

Using pytest

Using nox

📦 Configuration

Badge Customization

Example

Output

Project Logo

🔭 Roadmap

📒 Changelog

🧑‍💻 Contributing

🎗 License

👊 Acknowledgments

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Using `pip`

Using `docker`

Using `conda`

From `source`

Using `bash`

Using `poetry`

Using `OpenAI`

Using `Ollama`

Using `Google Gemini`

Using `pip`

Using `docker`

Using `streamlit`

From `source`

Using `bash`

Using `poetry`

Using `pytest`

Using `nox`

Packages