<p align="center">
<img src="https://img.icons8.com/?size=512&id=55494&format=png" width="99">
<img src="https://img.icons8.com/?size=512&id=kTuxVYRKeKEY&format=png" width="99">
</p>
<h1 align="center">README-AI</h1>
<p align="center">
<em>Automated <code>README</code> file generator, powered by large language model APIs</em>
</p>
<p align="center">
<a href="https://github.com/eli64s/readme-ai/actions">
<img src="https://img.shields.io/github/actions/workflow/status/eli64s/readme-ai/release-pipeline.yml?logo=githubactions&label=CICD&logoColor=white&color=c125ff"
alt="github-actions">
</a>
<a href="https://app.codecov.io/gh/eli64s/readme-ai">
<img src="https://img.shields.io/codecov/c/github/eli64s/readme-ai?logo=codecov&logoColor=white&label=Coverage&color=c125ff"
alt="codecov">
</a>
<a href="https://pypi.python.org/pypi/readmeai/">
<img src="https://img.shields.io/pypi/v/readmeai?logo=Python&logoColor=white&label=PyPI&color=c125ff" alt="pypi-version">
</a>
<a href="https://www.pepy.tech/projects/readmeai">
<img src="https://img.shields.io/pepy/dt/readmeai?logo=PyPI&logoColor=white&label=Downloads&color=c125ff"
alt="pepy-total-downloads">
</a>
<a href="https://opensource.org/license/mit/">
<img src="https://img.shields.io/github/license/eli64s/readme-ai?logo=opensourceinitiative&logoColor=white&label=License&color=c125ff"
alt="license">
</a>
</p>
<!-- TABLE OF CONTENTS -->
<details>
<summary>Table of Contents</summary>
- [📍 Overview](#-overview)
- [👾 Demo](#-demo)
- [🧩 Features](#-features)
- [🗂️ Examples](#️-examples)
- [🚀 Getting Started](#-getting-started)
- [⚙️ Installation](#-installation)
- [🤖 Usage](#-usage)
- [🧪 Tests](#-tests)
- [📦 Configuration](#️-configuration)
- [🔭 Roadmap](#-roadmap)
- [🧑💻 Contributing](#-contributing)
- [🎗 License](#-license)
</details>
---
## 📍 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.<br>
> [!IMPORTANT]
>
> <sub>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.</sub>
---
## 👾 Demo
**Standard CLI Usage:**
[readmeai-cli-demo](https://github.com/eli64s/artifacts/assets/43382407/55b8d1b9-06a7-4b1f-b6a7-aaeccdb27679
)
**Offline Mode Demonstration:**
[readmeai-streamlit-demo](https://github.com/eli64s/artifacts/assets/43382407/3eb39fcf-c1df-49c6-bb5c-63e141857ae3)
> [!TIP]
>
> <sub>Offline mode is useful for generating a boilerplate README at no cost. View the offline README.md example [here!](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-offline.md)</sub>
---
## 🧩 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](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-offline.md) 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](https://shields.io/), 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:
<table>
<!-- row 1 -->
<tr>
<td colspan="2" align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-default.png" alt="default-header" width="900"/><br>
<code>default output (no options provided to cli)</code>
</td>
</tr>
<!-- row 2 -->
<tr>
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-cloud.png" alt="cloud-db-logo" width="450"/><br>
<code>--alignment left --badge-style flat-square --image cloud</code>
</td>
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-gradient.png" alt="gradient-markdown-logo" width="450"/><br>
<code>--alignment left --badge-style flat --image gradient</code>
</td>
</tr>
<!-- row 3 -->
<tr>
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-custom.png" alt="custom-logo" width="450"/><br>
<code>--badge-style flat --image custom</code>
</td>
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-skills.png" alt="skills-light" width="450"/><br>
<code>--badge-style skills-light --image grey</code>
</td>
</tr>
<tr>
<!-- row 4 -->
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-flat-square.png" alt="readme-ai-header" width="450"/><br>
<code>--badge-style flat-square</code>
</td>
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-black.png" alt="black-logo" width="450"/><br>
<code>--badge-style flat --image black</code>
</td>
</tr>
</table>
See the <a href="https://github.com/eli64s/readme-ai?tab=readme-ov-file#%EF%B8%8F-configuration">Configuration</a> section for a complete list of CLI options.
<details closed>
<summary><strong>👋 Overview</strong></summary><br>
<table>
<tr>
<td><b>Overview</b><br>
<p>
<ol>
- High-level introduction of the project, focused on the value proposition and use-cases, rather than technical aspects.
</ol>
</td>
</tr>
<tr>
<td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/llm-overview.png" alt="llm-overview" width="700" /></td>
</tr>
</table>
</details>
<details closed>
<summary><strong>🧩 Features</strong></summary><br>
<table>
<tr>
<td><b>Features Table</b><br>
<p>
<ol>
- Generated markdown table that highlights the key technical features and components of the codebase. This table is generated using a structured <a href="https://github.com/eli64s/readme-ai/blob/main/readmeai/config/settings/prompts.toml#L18">prompt template.</a>
</ol>
</p>
</td>
</tr>
<tr>
<td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/llm-features.png" alt="llm-features" width="700" /></td>
</tr>
</table>
</details>
<details closed>
<summary><strong>📄 Codebase Documentation</strong></summary><br>
<table>
<tr>
<td><b>Repository Structure</b><br>
<p>
<ol>
- Directory tree structure is generated using pure Python <a href="https://github.com/eli64s/readme-ai/blob/main/readmeai/generators/tree.py">(tree.py)</a> and embedded in the README.
</ol>
</p>
</td>
</tr>
<tr>
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/directory-tree.png" alt="directory-tree" width="700" />
</td>
</tr>
<tr>
<td style="padding-top:20px;">
<b>File Summaries</b><br>
<p>
<ol>
- Summarizes key files in the codebase, and also used as context for additional <a href="https://github.com/eli64s/readme-ai/blob/main/readmeai/config/settings/prompts.toml#L3">prompts!</a>
</ol>
</p>
</td>
</tr>
<tr>
<td align="center">
<img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/llm-summaries.png" alt="llm-summaries" width="700" />
</td>
</tr>
</table>
</details>
<details closed>
<summary><strong>🚀 Quickstart Commands</strong></summary>
<br>
<table>
<tr>
<td><b>Getting Started</b><br>
<p>
<ol>
- Auto-generated setup guides based on <em>language</em> and <em>dependency</em> analysis.
</ol>
<ol>
- <code>Install</code>, <code>Usage</code>, and <code>Test</code> guides are supported for many languages.
</ol>
<ol>
- The <a href="https://github.com/eli64s/readme-ai/tree/main/readmeai/parsers">parsers</a> module is a collection of tool-specific parsers that extract dependencies and metadata.
</ol>
</p>
</td>
</tr>
<tr>
<td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/quickstart.png" alt="quick-start" width="700" />
</td>
</tr>
</table>
</details>
<details closed>
<summary><strong>🔰 Contributing Guidelines</strong></summary>
<br>
<table>
<tr>
<td><b>Contributing Guide</b><br>
<p>
<ol>- Dropdown section that outlines general process for contributing to your project.</ol>
<ol>- Provides links to your contributing guidelines, issues page, and more resources.</ol>
<ol>- Graph of contributors is also included.</ol>
</p>
</td>
</tr>
<tr>
<td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/contributing-guidelines.png" alt="contributing-guidelines" width="700" /></td>
</tr>
<tr>
<td><b>Additional Sections</b><br>
<p>
<ol>
- <code>Project Roadmap</code>, <code>Contributing Guidelines</code>, <code>License</code>, and <code>Acknowledgements</code> are included by default.
</ol>
</p>
</td>
</tr>
<tr>
<td align="center"><img src="https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/additional-sections.png" alt="contributing-and-more" width="700" /></td>
</tr>
</table>
</details>
<details closed>
<summary><strong>🎨 Templates (wip)</strong></summary>
<br>
<table>
<tr>
<td><b>README Template for ML & Data</b>
<p>
<ol>- Themed templates tailored to AI, web, data science projects.</ol>
<ol>- Sections targetted to programming domain.</ol>
<ol>- Framework for consistent, comprehensive READMEs</ol>
</p>
</td>
</tr>
<tr>
<td>
<ul>
<li><a href="#overview">Overview</a>: Project objectives, scope, outcomes.</li>
<li><a href="#project-structure">Project Structure</a>: Organization and components.</li>
<li><a href="#data-preprocessing">Data Preprocessing</a>: Data sources and methods.</li>
<li><a href="#feature-engineering">Feature Engineering</a>: Impact on model performance.</li>
<li><a href="#model-architecture">Model Architecture</a>: Selection and development strategies.</li>
<li><a href="#training-and-validation">Training</a>: Procedures, tuning, strategies.</li>
<li><a href="#testing-and-evaluation">Testing and Evaluation</a>: Results, analysis, benchmarks.</li>
<li><a href="#deployment">Deployment</a>: System integration, APIs.</li>
<li><a href="#usage">Usage and Maintenance</a>: User guide, model upkeep.</li>
<li><a href="#results">Results and Discussion</a>: Implications, future work.</li>
<li><a href="#ethical-considerations">Ethical Considerations</a>: Ethics, privacy, fairness.</li>
<li><a href="#contributing">Contributing</a>: Contribution guidelines.</li>
<li><a href="#acknowledgements">Acknowledgements</a>: Credits, resources used.</li>
<li><a href="#license">License</a>: Usage rights, restrictions.</li>
</ul>
</td>
</tr>
</table>
</details>
---
## 🗂️ Examples
| | **Output File** | **Input Repository** | **Input Contents** |
|---|-------------|------------|-----------|
| ▹ | [readme-python.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-python.md) | [readme-ai](https://github.com/eli64s/readme-ai) | Python |
| ▹ | [readme-google-gemini.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-gemini.md) | [readme-ai](https://github.com/eli64s/readme-ai) | Python |
| ▹ | [readme-typescript.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-typescript.md) | [chatgpt-app-react-ts](https://github.com/Yuberley/ChatGPT-App-React-Native-TypeScript) | TypeScript, React |
| ▹ | [readme-postgres.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-postgres.md) | [postgres-proxy-server](https://github.com/jwills/buenavista) | Postgres, Duckdb |
| ▹ | [readme-kotlin.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-kotlin.md) | [file.io-android-client](https://github.com/rumaan/file.io-Android-Client) | Kotlin, Android |
| ▹ | [readme-streamlit.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-streamlit.md) | [readme-ai-streamlit](https://github.com/eli64s/readme-ai-streamlit) | Python, Streamlit |
| ▹ | [readme-rust-c.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-rust-c.md) | [rust-c-app](https://github.com/DownWithUp/CallMon) | C, Rust |
| ▹ | [readme-go.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-go.md) | [go-docker-app](https://github.com/olliefr/docker-gs-ping) | Go |
| ▹ | [readme-java.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-java.md) | [java-minimal-todo](https://github.com/avjinder/Minimal-Todo) | Java |
| ▹ | [readme-fastapi-redis.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-fastapi-redis.md) | [async-ml-inference](https://github.com/FerrariDG/async-ml-inference) | FastAPI, Redis |
| ▹ | [readme-mlops.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-mlops.md) | [mlops-course](https://github.com/GokuMohandas/mlops-course) | Python, Jupyter |
| ▹ | [readme-local.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-local.md) | Local Directory | Flink, Python |
<!--
| ▹ | [readme-gitlab.md]() | [gitlab](https://github.com/eli64s/flink-flow) | GitLab |
| ▹ | [readme-bitbucket.md]() | [bitbucket](https://github.com/eli64s/flink-flow) | BitBucket |
-->
---
## 🚀 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.
- [**GitHub**](https://github.com/)
- [**GitLab**](https://gitlab.com/)
- [**Bitbucket**](https://bitbucket.org/)
- [**File System**](https://en.wikipedia.org/wiki/File_system)
**Choosing an LLM Service:**
- [**OpenAI**](https://platform.openai.com/docs/quickstart/account-setup): Recommended, requires an account setup and API key.
- [**Ollama**](https://github.com/ollama/ollama): Free and open-source, potentially slower and more resource-intensive.
- [**Google Gemini**](https://ai.google.dev/tutorials/python_quickstart): Requires a Google Cloud account and API key.
- [**Offline Mode**](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-offline.md): Generates a boilerplate README without making API calls.
<!--
**OpenAI API Key**
An OpenAI API account and API key are needed to use readme-ai. Get started by creating an account [here](https://platform.openai.com/docs/quickstart/account-setup). Once you have an account, you can create an API key on the [API settings page](https://platform.openai.com/api-keys).
> [!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](https://platform.openai.com/account/usage).
-->
---
### ⚙️ Installation
#### Using `pip`
> [](https://pypi.org/project/readmeai/)
>
> ```sh
> pip install readmeai
> ```
> [!TIP]
>
> [](https://pipxproject.github.io/pipx/installation/)
>
> <sub>Use [pipx](https://pipx.pypa.io/stable/installation/) to install and run Python command-line applications without causing dependency conflicts with other packages!</sub>
#### Using `docker`
> [](https://hub.docker.com/r/zeroxeli/readme-ai)
>
> ```sh
> docker pull zeroxeli/readme-ai:latest
> ```
#### Using `conda`
> [](https://anaconda.org/zeroxeli/readmeai)
>
> ```sh
> conda install -c conda-forge readmeai
> ```
#### From `source`
<details closed>
<summary>Clone and Install</summary><br>
> Clone repository and change directory.
>
> ```console
> $ git clone https://github.com/eli64s/readme-ai
> $ cd readme-ai
> ```
#### Using `bash`
>
> [](https://www.gnu.org/software/bash/)
>
> ```console
> $ bash setup/setup.sh
> ```
#### Using `poetry`
> [](https://python-poetry.org/)
>
> ```console
> $ poetry install
> ```
* <sub>Similiary you can use `pipenv` or `pip` to install the requirements.txt.</sub>
</details>
---
### 🤖 Usage
**Environment Variables**
#### Using `OpenAI`
> Set your OpenAI API key as an environment variable.
> ```console
> # Using Linux or macOS
> $ export OPENAI_API_KEY=<your_api_key>
>
> # Using Windows
> $ set OPENAI_API=<your_api_key>
> ```
#### Using `Ollama`
> Set Ollama local host as an environment variable.
> ```console
> $ export OLLAMA_HOST=127.0.0.1
> $ ollama pull mistral:latest # llama2, etc.
> $ ollama serve # run if not using the Ollama desktop app
> ```
> <sub>For more details, check out the [Ollama](https://github.com/ollama/ollama-python?tab=readme-ov-file) repository.</sub>
#### Using `Google Gemini`
> Set your Google Cloud project ID and location as environment variables.
> ```console
> $ export GOOGLE_API_KEY=<your_api_key>
> ```
**Run the CLI**
#### Using `pip`
> [](https://pypi.org/project/readmeai/)
>
> ```console
> # 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`
> [](https://hub.docker.com/r/zeroxeli/readme-ai)
>
> ```sh
> 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`
> [](https://readme-ai.streamlit.app/)
>
> <sub>Try directly in your browser on <a href="https://streamlit.io/">Streamlit</a>, no installation required! For more details, check out the <a href="https://github.com/eli64s/readme-ai-streamlit">readme-ai-streamlit</a> repository.</sub>
#### From `source`
<details closed>
<summary>Usage</summary><br>
#### Using `bash`
>
> [](https://www.gnu.org/software/bash/)
>
> ```console
> $ conda activate readmeai
> $ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
> ```
#### Using `poetry`
> [](https://python-poetry.org/)
>
> ```console
> $ poetry shell
> $ poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
> ```
</details>
---
### 🧪 Tests
#### Using `pytest`
> [](https://docs.pytest.org/en/7.1.x/contents.html)
> ```console
> $ make pytest
> ```
#### Using `nox`
> ```console
> $ nox -f noxfile.py
> ```
> [!TIP]
>
> <sub>Use [nox](https://nox.thea.codes/en/stable/) to test application against multiple Python environments and dependencies!</sub>
---
## 📦 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][0] |
| `--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. | |
<sub><code>🚧 feature under development</code></sub>
[0]: https://github.com/eli64s/readme-ai?tab=readme-ov-file#badges "see below"
---
### Badge Customization
The `--badge-style` option lets you select the style of the default badge set.
<table>
<tr>
<th style="text-align: left;">Style</th>
<th style="text-align: center;">Preview</th>
</tr>
<tr>
<td><strong>default</strong></td>
<td align="center"><a href="https://img.shields.io/github/license/eli64s/readme-ai?flat&color=0080ff&logo=opensourceinitiative&logoColor=white" target="_blank"><img src="https://img.shields.io/github/license/eli64s/readme-ai?flat&color=0080ff&logo=opensourceinitiative&logoColor=white"></a> <a href="https://img.shields.io/github/last-commit/eli64s/readme-ai?flat&color=0080ff&logo=git&logoColor=white" target="_blank"><img src="https://img.shields.io/github/last-commit/eli64s/readme-ai?flat&color=0080ff&logo=git&logoColor=white"></a> <a href="https://img.shields.io/github/languages/top/eli64s/readme-ai?flat&color=0080ff" target="_blank"><img src="https://img.shields.io/github/languages/top/eli64s/readme-ai?flat&color=0080ff"></a> <a href="https://img.shields.io/github/languages/count/eli64s/readme-ai?flat&color=0080ff" target="_blank"><img src="https://img.shields.io/github/languages/count/eli64s/readme-ai?flat&color=0080ff"></a></td>
</tr>
<tr>
<td><strong>flat</strong></td>
<td align="center"><a href="https://img.shields.io/badge/Python-3776AB.svg?&style=flat&logo=Python&logoColor=white" target="_blank"><img src="https://img.shields.io/badge/Python-3776AB.svg?&style=flat&logo=Python&logoColor=white"></a></td>
</tr>
<tr>
<td><strong>flat-square</strong></td>
<td align="center"><a href="https://img.shields.io/badge/Python-3776AB.svg?&style=flat-square&logo=Python&logoColor=white" target="_blank"><img src="https://img.shields.io/badge/Python-3776AB.svg?&style=flat-square&logo=Python&logoColor=white"></a></td>
</tr>
<tr>
<td><strong>for-the-badge</strong></td>
<td align="center"><a href="https://img.shields.io/badge/Python-3776AB.svg?&style=for-the-badge&logo=Python&logoColor=white" target="_blank"><img src="https://img.shields.io/badge/Python-3776AB.svg?&style=for-the-badge&logo=Python&logoColor=white"></a></td>
</tr>
<tr>
<td><strong>plastic</strong></td>
<td align="center"><a href="https://img.shields.io/badge/Python-3776AB.svg?&style=plastic&logo=Python&logoColor=white" target="_blank"><img src="https://img.shields.io/badge/Python-3776AB.svg?&style=plastic&logo=Python&logoColor=white"></a></td>
</tr>
<tr>
<td><strong>skills</strong></td>
<td align="center"><a href="https://skillicons.dev/" target="_blank"><img src="https://skillicons.dev/icons?i=py" alt="Python Skill Icon"></a></td>
</tr>
<tr>
<td><strong>skills-light</strong></td>
<td align="center"><a href="https://skillicons.dev/" target="_blank"><img src="https://skillicons.dev/icons?i=py&theme=light" alt="Python Skill Light Icon"></a></td>
</tr>
<tr>
<td><strong>social</strong></td>
<td align="center"><a href="https://img.shields.io/badge/Python-3776AB.svg?&style=social&logo=Python&logoColor=white" target="_blank"><img src="https://img.shields.io/badge/Python-3776AB.svg?&style=social&logo=Python&logoColor=white"></a></td>
</tr>
</table>
When providing the `--badge-style` 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.)
#### Example
>
> ```console
> $ readmeai --badge-style flat-square --repository https://github.com/eli64s/readme-ai
> ```
>
#### Output
>
> {... project logo ...}
>
> {... project name ...}
>
> {...project slogan...}
>
> <img src="https://img.shields.io/github/license/eli64s/readme-ai?style=flat-square&color=0080ff&logo=opensourceinitiative&logoColor=white">
> <img src="https://img.shields.io/github/last-commit/eli64s/readme-ai?style=flat-square&color=0080ff&logo=git&logoColor=white">
> <img src="https://img.shields.io/github/languages/top/eli64s/readme-ai?style=flat-square&color=0080ff">
> <img src="https://img.shields.io/github/languages/count/eli64s/readme-ai?style=flat-square&color=0080ff">
>
> <br>
>
> *Developed with the software and tools below.*
>
> <img src="https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat-square&logo=GNU-Bash&logoColor=white">
> <img src="https://img.shields.io/badge/tqdm-FFC107.svg?style=flat-square&logo=tqdm&logoColor=black">
> <img src="https://img.shields.io/badge/Pydantic-E92063.svg?style=flat-square&logo=Pydantic&logoColor=white">
> <img src="https://img.shields.io/badge/YAML-CB171E.svg?style=flat-square&logo=YAML&logoColor=white" alt="YAML">
> <img src="https://img.shields.io/badge/Poetry-60A5FA.svg?style=flat-square&logo=Poetry&logoColor=white">
> <img src="https://img.shields.io/badge/OpenAI-412991.svg?style=flat-square&logo=OpenAI&logoColor=white">
> <br>
> <img src="https://img.shields.io/badge/Python-3776AB.svg?style=flat-square&logo=Python&logoColor=white">
> <img src="https://img.shields.io/badge/AIOHTTP-2C5BB4.svg?style=flat-square&logo=AIOHTTP&logoColor=white">
> <img src="https://img.shields.io/badge/Docker-2496ED.svg?style=flat-square&logo=Docker&logoColor=white">
> <img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat-square&logo=GitHub-Actions&logoColor=white">
> <img src="https://img.shields.io/badge/Pytest-0A9EDC.svg?style=flat-square&logo=Pytest&logoColor=white">
>
> <br>
>
> {... end of header ...}
>
---
### Project Logo
Select a project logo using the `--image` option.
<table>
<tr>
<td><strong>blue</strong></td>
<td><strong>gradient</strong></td>
<td><strong>black</strong></td>
</tr>
<tr>
<td><img src="https://raw.githubusercontent.com/PKief/vscode-material-icon-theme/ec559a9f6bfd399b82bb44393651661b08aaf7ba/icons/folder-markdown-open.svg" width="100"></td>
<td><img src="https://img.icons8.com/?size=512&id=55494&format=png" width="100"></td>
<td><img src="https://img.icons8.com/external-tal-revivo-regular-tal-revivo/96/external-readme-is-a-easy-to-build-a-developer-hub-that-adapts-to-the-user-logo-regular-tal-revivo.png" width="100"></td>
</tr>
<tr>
<td><strong>cloud</strong></td>
<td><strong>purple</strong></td>
<td><strong>grey</strong></td>
</tr>
<tr>
<td><img src="https://cdn-icons-png.flaticon.com/512/6295/6295417.png" width="100"></td>
<td><img src="https://img.icons8.com/external-tal-revivo-duo-tal-revivo/100/external-markdown-a-lightweight-markup-language-with-plain-text-formatting-syntax-logo-duo-tal-revivo.png" width="100"></td>
<td><img src="https://img.icons8.com/external-tal-revivo-filled-tal-revivo/96/external-markdown-a-lightweight-markup-language-with-plain-text-formatting-syntax-logo-filled-tal-revivo.png" width="100"></td>
</tr>
</table>
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.
- [X] `--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][0]
---
## 🧑💻 Contributing
To grow the project, we need your help! See the links below to get started.
- [🔰 Contributing Guide][1]
- [👋 Start a Discussion][2]
- [🐛 Open an Issue][3]
<br>
<p align="left">
<a href="https://github.com{/eli64s/readme-ai/}graphs/contributors">
<img src="https://contrib.rocks/image?repo=eli64s/readme-ai">
</a>
</p>
---
## 🎗 License
[MIT][4]
---
## 👊 Acknowledgments
- [Shields.io](https://shields.io/)
- [Aveek-Saha/GitHub-Profile-Badges](https://github.com/Aveek-Saha/GitHub-Profile-Badges)
- [Ileriayo/Markdown-Badges](https://github.com/Ileriayo/markdown-badges)
- [tandpfun/skill-icons](https://github.com/tandpfun/skill-icons)
<p align="right">
<a href="#-overview"><b>Return</b></a>
</p>
---
[0]: https://github.com/eli64s/readme-ai/blob/main/CHANGELOG.md "📒 Changelog"
[1]: https://github.com/eli64s/readme-ai/blob/main/CONTRIBUTING.md "🔰 Contributing Guide"
[2]: https://github.com/eli64s/readme-ai/discussions "👋 Start a Discussion"
[3]: https://github.com/eli64s/readme-ai/issues "🐛 Open an Issue"
[4]: https://github.com/eli64s/readme-ai/blob/main/LICENSE "🎗 License"
Raw data
{
"_id": null,
"home_page": "https://github.com/eli64s/readme-ai",
"name": "readmeai",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "python,markdown,readme,readme-md,devtools,developer-tools,documentation,documentation-generator,large-language-models,generative-ai,readme-generator,readme-md-generator,readme-badges,shieldsio-badges,ollama,openai,chatgpt,gpt-4,genai,ai",
"author": "Eli",
"author_email": "egsalamie@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/82/cd/8dc88c400ab7834b87d121b2f860b481ce31b7872c8f13fad87f82dc9fcb/readmeai-0.5.79.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://img.icons8.com/?size=512&id=55494&format=png\" width=\"99\">\n <img src=\"https://img.icons8.com/?size=512&id=kTuxVYRKeKEY&format=png\" width=\"99\">\n</p>\n<h1 align=\"center\">README-AI</h1>\n<p align=\"center\">\n <em>Automated <code>README</code> file generator, powered by large language model APIs</em>\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/eli64s/readme-ai/actions\">\n <img src=\"https://img.shields.io/github/actions/workflow/status/eli64s/readme-ai/release-pipeline.yml?logo=githubactions&label=CICD&logoColor=white&color=c125ff\"\n alt=\"github-actions\">\n </a>\n <a href=\"https://app.codecov.io/gh/eli64s/readme-ai\">\n <img src=\"https://img.shields.io/codecov/c/github/eli64s/readme-ai?logo=codecov&logoColor=white&label=Coverage&color=c125ff\"\n alt=\"codecov\">\n </a>\n <a href=\"https://pypi.python.org/pypi/readmeai/\">\n <img src=\"https://img.shields.io/pypi/v/readmeai?logo=Python&logoColor=white&label=PyPI&color=c125ff\" alt=\"pypi-version\">\n </a>\n <a href=\"https://www.pepy.tech/projects/readmeai\">\n <img src=\"https://img.shields.io/pepy/dt/readmeai?logo=PyPI&logoColor=white&label=Downloads&color=c125ff\"\n alt=\"pepy-total-downloads\">\n </a>\n <a href=\"https://opensource.org/license/mit/\">\n <img src=\"https://img.shields.io/github/license/eli64s/readme-ai?logo=opensourceinitiative&logoColor=white&label=License&color=c125ff\"\n alt=\"license\">\n </a>\n</p>\n\n<!-- TABLE OF CONTENTS -->\n<details>\n <summary>Table of Contents</summary>\n\n- [\ud83d\udccd Overview](#-overview)\n- [\ud83d\udc7e Demo](#-demo)\n- [\ud83e\udde9 Features](#-features)\n- [\ud83d\uddc2\ufe0f Examples](#\ufe0f-examples)\n- [\ud83d\ude80 Getting Started](#-getting-started)\n - [\u2699\ufe0f Installation](#-installation)\n - [\ud83e\udd16 Usage](#-usage)\n - [\ud83e\uddea Tests](#-tests)\n- [\ud83d\udce6 Configuration](#\ufe0f-configuration)\n- [\ud83d\udd2d Roadmap](#-roadmap)\n- [\ud83e\uddd1\u200d\ud83d\udcbb Contributing](#-contributing)\n- [\ud83c\udf97 License](#-license)\n</details>\n\n---\n\n## \ud83d\udccd Overview\n\n***Objective***\n\nReadme-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.\n\n***Motivation***\n\nStreamlines 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.<br>\n\n> [!IMPORTANT]\n>\n> <sub>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.</sub>\n\n---\n\n## \ud83d\udc7e Demo\n\n**Standard CLI Usage:**\n\n[readmeai-cli-demo](https://github.com/eli64s/artifacts/assets/43382407/55b8d1b9-06a7-4b1f-b6a7-aaeccdb27679\n)\n\n**Offline Mode Demonstration:**\n\n[readmeai-streamlit-demo](https://github.com/eli64s/artifacts/assets/43382407/3eb39fcf-c1df-49c6-bb5c-63e141857ae3)\n\n> [!TIP]\n>\n> <sub>Offline mode is useful for generating a boilerplate README at no cost. View the offline README.md example [here!](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-offline.md)</sub>\n\n---\n\n## \ud83e\udde9 Features\n\n### Flexible README Generation\n\nReadme-ai uses a balanced approach to building README files, combining data extraction and generative AI to create comprehensive and informative documentation.\n\n- **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.\n- **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.\n\n### CLI Customization\n\nOver a dozen CLI options are available to customize the README generation process:\n\n- **LLM Options**: Run the tool with OpenAI, Ollama, Google Gemini, or in offline mode.\n- **Offline Mode**: Generate a [README](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-offline.md) without making API calls. Readme-ai is still able to populate a significant portion of the README using metadata collected during preprocessing.\n- **Project Badges**: Choose from an array of [badge styles](https://shields.io/), colors, and alignments.\n- **Project Logo**: Select from the default set, upload your own, or let the LLM give it a try!\n\nA few examples of the CLI options in action:\n\n<table>\n <!-- row 1 -->\n <tr>\n <td colspan=\"2\" align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-default.png\" alt=\"default-header\" width=\"900\"/><br>\n <code>default output (no options provided to cli)</code>\n </td>\n </tr>\n <!-- row 2 -->\n <tr>\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-cloud.png\" alt=\"cloud-db-logo\" width=\"450\"/><br>\n <code>--alignment left --badge-style flat-square --image cloud</code>\n </td>\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-gradient.png\" alt=\"gradient-markdown-logo\" width=\"450\"/><br>\n <code>--alignment left --badge-style flat --image gradient</code>\n </td>\n </tr>\n <!-- row 3 -->\n <tr>\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-custom.png\" alt=\"custom-logo\" width=\"450\"/><br>\n <code>--badge-style flat --image custom</code>\n </td>\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-skills.png\" alt=\"skills-light\" width=\"450\"/><br>\n <code>--badge-style skills-light --image grey</code>\n </td>\n </tr>\n <tr>\n <!-- row 4 -->\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-flat-square.png\" alt=\"readme-ai-header\" width=\"450\"/><br>\n <code>--badge-style flat-square</code>\n </td>\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/header-black.png\" alt=\"black-logo\" width=\"450\"/><br>\n <code>--badge-style flat --image black</code>\n </td>\n </tr>\n</table>\n\nSee the <a href=\"https://github.com/eli64s/readme-ai?tab=readme-ov-file#%EF%B8%8F-configuration\">Configuration</a> section for a complete list of CLI options.\n\n<details closed>\n <summary><strong>\ud83d\udc4b Overview</strong></summary><br>\n <table>\n <tr>\n <td><b>Overview</b><br>\n <p>\n <ol>\n - High-level introduction of the project, focused on the value proposition and use-cases, rather than technical aspects.\n </ol>\n </td>\n </tr>\n <tr>\n <td align=\"center\"><img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/llm-overview.png\" alt=\"llm-overview\" width=\"700\" /></td>\n </tr>\n </table>\n</details>\n\n<details closed>\n <summary><strong>\ud83e\udde9 Features</strong></summary><br>\n <table>\n <tr>\n <td><b>Features Table</b><br>\n <p>\n <ol>\n - Generated markdown table that highlights the key technical features and components of the codebase. This table is generated using a structured <a href=\"https://github.com/eli64s/readme-ai/blob/main/readmeai/config/settings/prompts.toml#L18\">prompt template.</a>\n </ol>\n </p>\n </td>\n </tr>\n <tr>\n <td align=\"center\"><img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/llm-features.png\" alt=\"llm-features\" width=\"700\" /></td>\n </tr>\n </table>\n</details>\n\n<details closed>\n <summary><strong>\ud83d\udcc4 Codebase Documentation</strong></summary><br>\n <table>\n <tr>\n <td><b>Repository Structure</b><br>\n <p>\n <ol>\n - Directory tree structure is generated using pure Python <a href=\"https://github.com/eli64s/readme-ai/blob/main/readmeai/generators/tree.py\">(tree.py)</a> and embedded in the README.\n </ol>\n </p>\n </td>\n </tr>\n <tr>\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/directory-tree.png\" alt=\"directory-tree\" width=\"700\" />\n </td>\n </tr>\n <tr>\n <td style=\"padding-top:20px;\">\n <b>File Summaries</b><br>\n <p>\n <ol>\n - Summarizes key files in the codebase, and also used as context for additional <a href=\"https://github.com/eli64s/readme-ai/blob/main/readmeai/config/settings/prompts.toml#L3\">prompts!</a>\n </ol>\n </p>\n </td>\n </tr>\n <tr>\n <td align=\"center\">\n <img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/llm-summaries.png\" alt=\"llm-summaries\" width=\"700\" />\n </td>\n </tr>\n </table>\n</details>\n\n<details closed>\n <summary><strong>\ud83d\ude80 Quickstart Commands</strong></summary>\n <br>\n <table>\n <tr>\n <td><b>Getting Started</b><br>\n <p>\n <ol>\n - Auto-generated setup guides based on <em>language</em> and <em>dependency</em> analysis.\n </ol>\n <ol>\n - <code>Install</code>, <code>Usage</code>, and <code>Test</code> guides are supported for many languages.\n </ol>\n <ol>\n - The <a href=\"https://github.com/eli64s/readme-ai/tree/main/readmeai/parsers\">parsers</a> module is a collection of tool-specific parsers that extract dependencies and metadata.\n </ol>\n </p>\n </td>\n </tr>\n <tr>\n <td align=\"center\"><img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/quickstart.png\" alt=\"quick-start\" width=\"700\" />\n </td>\n </tr>\n </table>\n</details>\n\n<details closed>\n <summary><strong>\ud83d\udd30 Contributing Guidelines</strong></summary>\n <br>\n <table>\n <tr>\n <td><b>Contributing Guide</b><br>\n <p>\n <ol>- Dropdown section that outlines general process for contributing to your project.</ol>\n <ol>- Provides links to your contributing guidelines, issues page, and more resources.</ol>\n <ol>- Graph of contributors is also included.</ol>\n </p>\n </td>\n </tr>\n <tr>\n <td align=\"center\"><img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/contributing-guidelines.png\" alt=\"contributing-guidelines\" width=\"700\" /></td>\n </tr>\n <tr>\n <td><b>Additional Sections</b><br>\n <p>\n <ol>\n - <code>Project Roadmap</code>, <code>Contributing Guidelines</code>, <code>License</code>, and <code>Acknowledgements</code> are included by default.\n </ol>\n </p>\n </td>\n </tr>\n <tr>\n <td align=\"center\"><img src=\"https://raw.githubusercontent.com/eli64s/readme-ai/main/examples/images/additional-sections.png\" alt=\"contributing-and-more\" width=\"700\" /></td>\n </tr>\n </table>\n</details>\n\n<details closed>\n <summary><strong>\ud83c\udfa8 Templates (wip)</strong></summary>\n <br>\n <table>\n <tr>\n <td><b>README Template for ML & Data</b>\n <p>\n <ol>- Themed templates tailored to AI, web, data science projects.</ol>\n <ol>- Sections targetted to programming domain.</ol>\n <ol>- Framework for consistent, comprehensive READMEs</ol>\n </p>\n </td>\n </tr>\n <tr>\n <td>\n <ul>\n <li><a href=\"#overview\">Overview</a>: Project objectives, scope, outcomes.</li>\n <li><a href=\"#project-structure\">Project Structure</a>: Organization and components.</li>\n <li><a href=\"#data-preprocessing\">Data Preprocessing</a>: Data sources and methods.</li>\n <li><a href=\"#feature-engineering\">Feature Engineering</a>: Impact on model performance.</li>\n <li><a href=\"#model-architecture\">Model Architecture</a>: Selection and development strategies.</li>\n <li><a href=\"#training-and-validation\">Training</a>: Procedures, tuning, strategies.</li>\n <li><a href=\"#testing-and-evaluation\">Testing and Evaluation</a>: Results, analysis, benchmarks.</li>\n <li><a href=\"#deployment\">Deployment</a>: System integration, APIs.</li>\n <li><a href=\"#usage\">Usage and Maintenance</a>: User guide, model upkeep.</li>\n <li><a href=\"#results\">Results and Discussion</a>: Implications, future work.</li>\n <li><a href=\"#ethical-considerations\">Ethical Considerations</a>: Ethics, privacy, fairness.</li>\n <li><a href=\"#contributing\">Contributing</a>: Contribution guidelines.</li>\n <li><a href=\"#acknowledgements\">Acknowledgements</a>: Credits, resources used.</li>\n <li><a href=\"#license\">License</a>: Usage rights, restrictions.</li>\n </ul>\n </td>\n </tr>\n </table>\n</details>\n\n---\n\n## \ud83d\uddc2\ufe0f Examples\n\n| | **Output File** | **Input Repository** | **Input Contents** |\n|---|-------------|------------|-----------|\n| \u25b9 | [readme-python.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-python.md) | [readme-ai](https://github.com/eli64s/readme-ai) | Python |\n| \u25b9 | [readme-google-gemini.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-gemini.md) | [readme-ai](https://github.com/eli64s/readme-ai) | Python |\n| \u25b9 | [readme-typescript.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-typescript.md) | [chatgpt-app-react-ts](https://github.com/Yuberley/ChatGPT-App-React-Native-TypeScript) | TypeScript, React |\n| \u25b9 | [readme-postgres.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-postgres.md) | [postgres-proxy-server](https://github.com/jwills/buenavista) | Postgres, Duckdb |\n| \u25b9 | [readme-kotlin.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-kotlin.md) | [file.io-android-client](https://github.com/rumaan/file.io-Android-Client) | Kotlin, Android |\n| \u25b9 | [readme-streamlit.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-streamlit.md) | [readme-ai-streamlit](https://github.com/eli64s/readme-ai-streamlit) | Python, Streamlit |\n| \u25b9 | [readme-rust-c.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-rust-c.md) | [rust-c-app](https://github.com/DownWithUp/CallMon) | C, Rust |\n| \u25b9 | [readme-go.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-go.md) | [go-docker-app](https://github.com/olliefr/docker-gs-ping) | Go |\n| \u25b9 | [readme-java.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-java.md) | [java-minimal-todo](https://github.com/avjinder/Minimal-Todo) | Java |\n| \u25b9 | [readme-fastapi-redis.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-fastapi-redis.md) | [async-ml-inference](https://github.com/FerrariDG/async-ml-inference) | FastAPI, Redis |\n| \u25b9 | [readme-mlops.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-mlops.md) | [mlops-course](https://github.com/GokuMohandas/mlops-course) | Python, Jupyter |\n| \u25b9 | [readme-local.md](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-local.md) | Local Directory | Flink, Python |\n\n<!--\n| \u25b9 | [readme-gitlab.md]() | [gitlab](https://github.com/eli64s/flink-flow) | GitLab |\n| \u25b9 | [readme-bitbucket.md]() | [bitbucket](https://github.com/eli64s/flink-flow) | BitBucket |\n-->\n\n---\n\n## \ud83d\ude80 Getting Started\n\n**System Requirements:**\n\n - Python 3.9+\n - Package manager/Container: `pip`, `pipx`, `docker`\n - LLM service: `OpenAI`, `Ollama`, `Google Gemini`, `Offline Mode`\n\n**Repository URL or Local Path:**\n\nMake sure to have a repository URL or local directory path ready for the CLI.\n\n- [**GitHub**](https://github.com/)\n- [**GitLab**](https://gitlab.com/)\n- [**Bitbucket**](https://bitbucket.org/)\n- [**File System**](https://en.wikipedia.org/wiki/File_system)\n\n**Choosing an LLM Service:**\n\n- [**OpenAI**](https://platform.openai.com/docs/quickstart/account-setup): Recommended, requires an account setup and API key.\n- [**Ollama**](https://github.com/ollama/ollama): Free and open-source, potentially slower and more resource-intensive.\n- [**Google Gemini**](https://ai.google.dev/tutorials/python_quickstart): Requires a Google Cloud account and API key.\n- [**Offline Mode**](https://github.com/eli64s/readme-ai/blob/main/examples/markdown/readme-offline.md): Generates a boilerplate README without making API calls.\n\n<!--\n**OpenAI API Key**\n\nAn OpenAI API account and API key are needed to use readme-ai. Get started by creating an account [here](https://platform.openai.com/docs/quickstart/account-setup). Once you have an account, you can create an API key on the [API settings page](https://platform.openai.com/api-keys).\n\n> [!WARNING]\n>\n> Before using readme-ai, its essential to understand the potential risks and costs associated with using AI-powered tools.\n>\n> * **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.\n>\n> * **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](https://platform.openai.com/account/usage).\n-->\n\n---\n\n### \u2699\ufe0f Installation\n\n#### Using `pip`\n\n> [](https://pypi.org/project/readmeai/)\n>\n> ```sh\n> pip install readmeai\n> ```\n\n> [!TIP]\n>\n> [](https://pipxproject.github.io/pipx/installation/)\n>\n> <sub>Use [pipx](https://pipx.pypa.io/stable/installation/) to install and run Python command-line applications without causing dependency conflicts with other packages!</sub>\n\n\n#### Using `docker`\n\n> [](https://hub.docker.com/r/zeroxeli/readme-ai)\n>\n> ```sh\n> docker pull zeroxeli/readme-ai:latest\n> ```\n\n#### Using `conda`\n\n> [](https://anaconda.org/zeroxeli/readmeai)\n>\n> ```sh\n> conda install -c conda-forge readmeai\n> ```\n\n\n#### From `source`\n\n<details closed>\n <summary>Clone and Install</summary><br>\n\n> Clone repository and change directory.\n>\n> ```console\n> $ git clone https://github.com/eli64s/readme-ai\n> $ cd readme-ai\n> ```\n\n#### Using `bash`\n>\n> [](https://www.gnu.org/software/bash/)\n>\n> ```console\n> $ bash setup/setup.sh\n> ```\n\n#### Using `poetry`\n> [](https://python-poetry.org/)\n>\n> ```console\n> $ poetry install\n> ```\n\n* <sub>Similiary you can use `pipenv` or `pip` to install the requirements.txt.</sub>\n\n</details>\n\n---\n\n### \ud83e\udd16 Usage\n\n**Environment Variables**\n\n#### Using `OpenAI`\n\n> Set your OpenAI API key as an environment variable.\n> ```console\n> # Using Linux or macOS\n> $ export OPENAI_API_KEY=<your_api_key>\n>\n> # Using Windows\n> $ set OPENAI_API=<your_api_key>\n> ```\n\n#### Using `Ollama`\n\n> Set Ollama local host as an environment variable.\n> ```console\n> $ export OLLAMA_HOST=127.0.0.1\n> $ ollama pull mistral:latest # llama2, etc.\n> $ ollama serve # run if not using the Ollama desktop app\n> ```\n> <sub>For more details, check out the [Ollama](https://github.com/ollama/ollama-python?tab=readme-ov-file) repository.</sub>\n\n#### Using `Google Gemini`\n\n> Set your Google Cloud project ID and location as environment variables.\n> ```console\n> $ export GOOGLE_API_KEY=<your_api_key>\n> ```\n\n**Run the CLI**\n\n#### Using `pip`\n\n> [](https://pypi.org/project/readmeai/)\n>\n> ```console\n> # Using OpenAI API\n> readmeai --repository https://github.com/eli64s/readme-ai --api openai\n>\n> # Using Ollama local model\n> readmeai --repository https://github.com/eli64s/readme-ai --api ollama --model mistral\n> ```\n\n#### Using `docker`\n\n> [](https://hub.docker.com/r/zeroxeli/readme-ai)\n>\n> ```sh\n> docker run -it \\\n> -e OPENAI_API_KEY=$OPENAI_API_KEY \\\n> -v \"$(pwd)\":/app zeroxeli/readme-ai:latest \\\n> -r https://github.com/eli64s/readme-ai\n> ```\n\n#### Using `streamlit`\n\n> [](https://readme-ai.streamlit.app/)\n>\n> <sub>Try directly in your browser on <a href=\"https://streamlit.io/\">Streamlit</a>, no installation required! For more details, check out the <a href=\"https://github.com/eli64s/readme-ai-streamlit\">readme-ai-streamlit</a> repository.</sub>\n\n#### From `source`\n\n<details closed>\n <summary>Usage</summary><br>\n\n#### Using `bash`\n>\n> [](https://www.gnu.org/software/bash/)\n>\n> ```console\n> $ conda activate readmeai\n> $ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai\n> ```\n\n#### Using `poetry`\n> [](https://python-poetry.org/)\n>\n> ```console\n> $ poetry shell\n> $ poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai\n> ```\n\n</details>\n\n---\n\n### \ud83e\uddea Tests\n\n#### Using `pytest`\n> [](https://docs.pytest.org/en/7.1.x/contents.html)\n> ```console\n> $ make pytest\n> ```\n\n#### Using `nox`\n> ```console\n> $ nox -f noxfile.py\n> ```\n\n> [!TIP]\n>\n> <sub>Use [nox](https://nox.thea.codes/en/stable/) to test application against multiple Python environments and dependencies!</sub>\n\n---\n\n## \ud83d\udce6 Configuration\n\nCustomize the README file using the CLI options below.\n\n| Option | Type | Description | Default Value |\n| ------ | ---- | ----------- | -------------- |\n| `--alignment`, `-a` | String | Align the text in the README.md file's header. | `center` |\n| `--api` | String | LLM API service to use for text generation. | `offline` |\n| `--badge-color` | String | Badge color name or hex code. | `0080ff` |\n| `--badge-style` | String | Badge icon style type. | [see below][0] |\n| `--base-url` | String | Base URL for the repository. | `v1/chat/completions` |\n| `--context-window` | Integer | Maximum context window of the LLM API. | `3999` |\n| `--emojis`, `-e` | Boolean | Adds emojis to the README.md file's header sections. | `False` |\n| `--image`, `-i` | String | Project logo image displayed in the README file header. | `blue` |\n| `\ud83d\udea7 --language` | String | Language for generating the README.md file. | `en` |\n| `--model`, `-m` | String | LLM API to use for text generation. | `gpt-3.5-turbo` |\n| `--output`, `-o` | String | Output file name for the README file. | `readme-ai.md` |\n| `--rate-limit` | Integer | Maximum number of API requests per minute. | `5` |\n| `--repository`, `-r` | String | Repository URL or local directory path. | `None` |\n| `--temperature`, `-t` | Float | Sets the creativity level for content generation. | `0.9` |\n| `\ud83d\udea7 --template` | String | README template style. | `default` |\n| `--top-p` | Float | Sets the probability of the top-p sampling method. | `0.9` |\n| `--tree-depth` | Integer | Maximum depth of the directory tree structure. | `2` |\n| `--help` | | Displays help information about the command and its options. | |\n\n<sub><code>\ud83d\udea7 feature under development</code></sub>\n\n[0]: https://github.com/eli64s/readme-ai?tab=readme-ov-file#badges \"see below\"\n\n---\n\n### Badge Customization\n\nThe `--badge-style` option lets you select the style of the default badge set.\n\n<table>\n <tr>\n <th style=\"text-align: left;\">Style</th>\n <th style=\"text-align: center;\">Preview</th>\n </tr>\n <tr>\n <td><strong>default</strong></td>\n <td align=\"center\"><a href=\"https://img.shields.io/github/license/eli64s/readme-ai?flat&color=0080ff&logo=opensourceinitiative&logoColor=white\" target=\"_blank\"><img src=\"https://img.shields.io/github/license/eli64s/readme-ai?flat&color=0080ff&logo=opensourceinitiative&logoColor=white\"></a> <a href=\"https://img.shields.io/github/last-commit/eli64s/readme-ai?flat&color=0080ff&logo=git&logoColor=white\" target=\"_blank\"><img src=\"https://img.shields.io/github/last-commit/eli64s/readme-ai?flat&color=0080ff&logo=git&logoColor=white\"></a> <a href=\"https://img.shields.io/github/languages/top/eli64s/readme-ai?flat&color=0080ff\" target=\"_blank\"><img src=\"https://img.shields.io/github/languages/top/eli64s/readme-ai?flat&color=0080ff\"></a> <a href=\"https://img.shields.io/github/languages/count/eli64s/readme-ai?flat&color=0080ff\" target=\"_blank\"><img src=\"https://img.shields.io/github/languages/count/eli64s/readme-ai?flat&color=0080ff\"></a></td>\n </tr>\n <tr>\n <td><strong>flat</strong></td>\n <td align=\"center\"><a href=\"https://img.shields.io/badge/Python-3776AB.svg?&style=flat&logo=Python&logoColor=white\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Python-3776AB.svg?&style=flat&logo=Python&logoColor=white\"></a></td>\n </tr>\n <tr>\n <td><strong>flat-square</strong></td>\n <td align=\"center\"><a href=\"https://img.shields.io/badge/Python-3776AB.svg?&style=flat-square&logo=Python&logoColor=white\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Python-3776AB.svg?&style=flat-square&logo=Python&logoColor=white\"></a></td>\n </tr>\n <tr>\n <td><strong>for-the-badge</strong></td>\n <td align=\"center\"><a href=\"https://img.shields.io/badge/Python-3776AB.svg?&style=for-the-badge&logo=Python&logoColor=white\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Python-3776AB.svg?&style=for-the-badge&logo=Python&logoColor=white\"></a></td>\n </tr>\n <tr>\n <td><strong>plastic</strong></td>\n <td align=\"center\"><a href=\"https://img.shields.io/badge/Python-3776AB.svg?&style=plastic&logo=Python&logoColor=white\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Python-3776AB.svg?&style=plastic&logo=Python&logoColor=white\"></a></td>\n </tr>\n <tr>\n <td><strong>skills</strong></td>\n <td align=\"center\"><a href=\"https://skillicons.dev/\" target=\"_blank\"><img src=\"https://skillicons.dev/icons?i=py\" alt=\"Python Skill Icon\"></a></td>\n </tr>\n <tr>\n <td><strong>skills-light</strong></td>\n <td align=\"center\"><a href=\"https://skillicons.dev/\" target=\"_blank\"><img src=\"https://skillicons.dev/icons?i=py&theme=light\" alt=\"Python Skill Light Icon\"></a></td>\n </tr>\n <tr>\n <td><strong>social</strong></td>\n <td align=\"center\"><a href=\"https://img.shields.io/badge/Python-3776AB.svg?&style=social&logo=Python&logoColor=white\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Python-3776AB.svg?&style=social&logo=Python&logoColor=white\"></a></td>\n </tr>\n</table>\n\nWhen providing the `--badge-style` option, readme-ai does two things:\n\n1. Formats the default badge set to match the selection (i.e. flat, flat-square, etc.).\n2. Generates an additional badge set representing your projects dependencies and tech stack (i.e. Python, Docker, etc.)\n\n#### Example\n>\n> ```console\n> $ readmeai --badge-style flat-square --repository https://github.com/eli64s/readme-ai\n> ```\n>\n\n#### Output\n>\n> {... project logo ...}\n>\n> {... project name ...}\n>\n> {...project slogan...}\n>\n> <img src=\"https://img.shields.io/github/license/eli64s/readme-ai?style=flat-square&color=0080ff&logo=opensourceinitiative&logoColor=white\">\n> <img src=\"https://img.shields.io/github/last-commit/eli64s/readme-ai?style=flat-square&color=0080ff&logo=git&logoColor=white\">\n> <img src=\"https://img.shields.io/github/languages/top/eli64s/readme-ai?style=flat-square&color=0080ff\">\n> <img src=\"https://img.shields.io/github/languages/count/eli64s/readme-ai?style=flat-square&color=0080ff\">\n>\n> <br>\n>\n>\t*Developed with the software and tools below.*\n>\n> <img src=\"https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat-square&logo=GNU-Bash&logoColor=white\">\n> <img src=\"https://img.shields.io/badge/tqdm-FFC107.svg?style=flat-square&logo=tqdm&logoColor=black\">\n> <img src=\"https://img.shields.io/badge/Pydantic-E92063.svg?style=flat-square&logo=Pydantic&logoColor=white\">\n> <img src=\"https://img.shields.io/badge/YAML-CB171E.svg?style=flat-square&logo=YAML&logoColor=white\" alt=\"YAML\">\n> <img src=\"https://img.shields.io/badge/Poetry-60A5FA.svg?style=flat-square&logo=Poetry&logoColor=white\">\n> <img src=\"https://img.shields.io/badge/OpenAI-412991.svg?style=flat-square&logo=OpenAI&logoColor=white\">\n> <br>\n> <img src=\"https://img.shields.io/badge/Python-3776AB.svg?style=flat-square&logo=Python&logoColor=white\">\n> <img src=\"https://img.shields.io/badge/AIOHTTP-2C5BB4.svg?style=flat-square&logo=AIOHTTP&logoColor=white\">\n> <img src=\"https://img.shields.io/badge/Docker-2496ED.svg?style=flat-square&logo=Docker&logoColor=white\">\n> <img src=\"https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat-square&logo=GitHub-Actions&logoColor=white\">\n> <img src=\"https://img.shields.io/badge/Pytest-0A9EDC.svg?style=flat-square&logo=Pytest&logoColor=white\">\n>\n> <br>\n>\n> {... end of header ...}\n>\n\n---\n\n### Project Logo\n\nSelect a project logo using the `--image` option.\n\n<table>\n <tr>\n <td><strong>blue</strong></td>\n <td><strong>gradient</strong></td>\n <td><strong>black</strong></td>\n </tr>\n <tr>\n <td><img src=\"https://raw.githubusercontent.com/PKief/vscode-material-icon-theme/ec559a9f6bfd399b82bb44393651661b08aaf7ba/icons/folder-markdown-open.svg\" width=\"100\"></td>\n <td><img src=\"https://img.icons8.com/?size=512&id=55494&format=png\" width=\"100\"></td>\n <td><img src=\"https://img.icons8.com/external-tal-revivo-regular-tal-revivo/96/external-readme-is-a-easy-to-build-a-developer-hub-that-adapts-to-the-user-logo-regular-tal-revivo.png\" width=\"100\"></td>\n </tr>\n <tr>\n <td><strong>cloud</strong></td>\n <td><strong>purple</strong></td>\n <td><strong>grey</strong></td>\n </tr>\n <tr>\n <td><img src=\"https://cdn-icons-png.flaticon.com/512/6295/6295417.png\" width=\"100\"></td>\n <td><img src=\"https://img.icons8.com/external-tal-revivo-duo-tal-revivo/100/external-markdown-a-lightweight-markup-language-with-plain-text-formatting-syntax-logo-duo-tal-revivo.png\" width=\"100\"></td>\n <td><img src=\"https://img.icons8.com/external-tal-revivo-filled-tal-revivo/96/external-markdown-a-lightweight-markup-language-with-plain-text-formatting-syntax-logo-filled-tal-revivo.png\" width=\"100\"></td>\n </tr>\n</table>\n\nFor custom images, see the following options:\n* Use `--image custom` to invoke a prompt to upload a local image file path or URL.\n* Use `--image llm` to generate a project logo using a LLM API (OpenAI only).\n\n---\n\n## \ud83d\udd2d Roadmap\n\n- [ ] Add new CLI options to enhance README file customization.\n - [X] `--api` Integrate singular interface for all LLM APIs (OpenAI, Ollama, Gemini, etc.)\n - [ ] `--audit` to review existing README files and suggest improvements.\n - [ ] `--template` to select a README template style (i.e. ai, data, web, etc.)\n - [ ] `--language` to generate README files in any language (i.e. zh-CN, ES, FR, JA, KO, RU)\n- [ ] Develop robust documentation generator to build full project docs (i.e. Sphinx, MkDocs)\n- [ ] Create community-driven templates for README files and gallery of readme-ai examples.\n- [ ] GitHub Actions script to automatically update README file content on repository push.\n\n---\n\n## \ud83d\udcd2 Changelog\n\n[Changelog][0]\n\n---\n\n## \ud83e\uddd1\u200d\ud83d\udcbb Contributing\n\nTo grow the project, we need your help! See the links below to get started.\n\n- [\ud83d\udd30 Contributing Guide][1]\n- [\ud83d\udc4b Start a Discussion][2]\n- [\ud83d\udc1b Open an Issue][3]\n\n<br>\n<p align=\"left\">\n <a href=\"https://github.com{/eli64s/readme-ai/}graphs/contributors\">\n <img src=\"https://contrib.rocks/image?repo=eli64s/readme-ai\">\n </a>\n</p>\n\n---\n\n## \ud83c\udf97 License\n\n[MIT][4]\n\n---\n\n## \ud83d\udc4a Acknowledgments\n\n- [Shields.io](https://shields.io/)\n- [Aveek-Saha/GitHub-Profile-Badges](https://github.com/Aveek-Saha/GitHub-Profile-Badges)\n- [Ileriayo/Markdown-Badges](https://github.com/Ileriayo/markdown-badges)\n- [tandpfun/skill-icons](https://github.com/tandpfun/skill-icons)\n\n<p align=\"right\">\n <a href=\"#-overview\"><b>Return</b></a>\n</p>\n\n---\n\n[0]: https://github.com/eli64s/readme-ai/blob/main/CHANGELOG.md \"\ud83d\udcd2 Changelog\"\n[1]: https://github.com/eli64s/readme-ai/blob/main/CONTRIBUTING.md \"\ud83d\udd30 Contributing Guide\"\n[2]: https://github.com/eli64s/readme-ai/discussions \"\ud83d\udc4b Start a Discussion\"\n[3]: https://github.com/eli64s/readme-ai/issues \"\ud83d\udc1b Open an Issue\"\n[4]: https://github.com/eli64s/readme-ai/blob/main/LICENSE \"\ud83c\udf97 License\"\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83d\udc7e Automated README file generator, powered by large language model APIs.",
"version": "0.5.79",
"project_urls": {
"Documentation": "https://eli64s.github.io/readme-ai",
"Homepage": "https://github.com/eli64s/readme-ai"
},
"split_keywords": [
"python",
"markdown",
"readme",
"readme-md",
"devtools",
"developer-tools",
"documentation",
"documentation-generator",
"large-language-models",
"generative-ai",
"readme-generator",
"readme-md-generator",
"readme-badges",
"shieldsio-badges",
"ollama",
"openai",
"chatgpt",
"gpt-4",
"genai",
"ai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5de79260c4240af6e8a842c86531384c51fddabbc06b36f23dda17431fde503a",
"md5": "bc77188638f2b78f84b68427398e9644",
"sha256": "5aaec7953dff65fb845d269fa329c3eb5583e5af3e643a543245dac29a6f9406"
},
"downloads": -1,
"filename": "readmeai-0.5.79-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bc77188638f2b78f84b68427398e9644",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 194071,
"upload_time": "2024-03-10T10:11:04",
"upload_time_iso_8601": "2024-03-10T10:11:04.985543Z",
"url": "https://files.pythonhosted.org/packages/5d/e7/9260c4240af6e8a842c86531384c51fddabbc06b36f23dda17431fde503a/readmeai-0.5.79-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "82cd8dc88c400ab7834b87d121b2f860b481ce31b7872c8f13fad87f82dc9fcb",
"md5": "aa5de4d06b59850830eae2f6bfe0c328",
"sha256": "03eb40cae2cb85756322902ae70ac9e411eea1a06c370caa197fff91c686d9f7"
},
"downloads": -1,
"filename": "readmeai-0.5.79.tar.gz",
"has_sig": false,
"md5_digest": "aa5de4d06b59850830eae2f6bfe0c328",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 178248,
"upload_time": "2024-03-10T10:11:09",
"upload_time_iso_8601": "2024-03-10T10:11:09.112783Z",
"url": "https://files.pythonhosted.org/packages/82/cd/8dc88c400ab7834b87d121b2f860b481ce31b7872c8f13fad87f82dc9fcb/readmeai-0.5.79.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-10 10:11:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eli64s",
"github_project": "readme-ai",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "readmeai"
}
JSON
