readmex 0.3.0

A tool to automatically generate README files for your projects.

English | 简体中文

---

readmex

🚀 AI-Powered README Generator: Automatically creates beautiful READMEs and interactive wikis for any repository! Can run all in local with your own models.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

📖 About The Project

AI-Powered README Generator is an AI-powered tool that automatically generates comprehensive Markdown README files for your projects. It crafts well-structured documentation that includes project details, technology stack, setup instructions, usage examples, badges, logos, and more.

Key Features

• 🤖 AI-Powered READMEs: Generate comprehensive Markdown READMEs instantly.
• 🔗 Auto Badges: Creates and embeds relevant status badges (contributors, forks, stars, etc.).
• 🖼️ Smart Logo Design: Crafts a unique project logo automatically.
• 🧠 Tech Stack Identification: Automatically detects and includes the project's technology stack.
• 🌐 Context-Aware Intelligence: Tailors content to your project's specific context and needs.

(back to top)

Built With

• 
• 
• 

(back to top)

🚀 Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple steps.

Prerequisites

• Python 3.7+

Installation

1. Install the package using pip:

   pip install readmex
   

Configuration

readmex requires API keys for both the Language Model (for generating text) and the Text-to-Image model (for generating logos). You can configure these in one of two ways. Environment variables take precedence.

1. Environment Variables (Recommended for CI/CD)

Set the following environment variables in your shell:

export LLM_API_KEY="your_llm_api_key"       # Required
export T2I_API_KEY="your_t2i_api_key"       # Required

# Optional: Specify custom API endpoints and models
export LLM_BASE_URL="https://api.example.com/v1"
export T2I_BASE_URL="https://api.example.com/v1"
export LLM_MODEL_NAME="your-llm-model"
export T2I_MODEL_NAME="your-t2i-model"

# Optional: Embedding model configuration for RAG (Retrieval-Augmented Generation)
export EMBEDDING_API_KEY="your_embedding_api_key"     # Optional, for web embedding models
export EMBEDDING_BASE_URL="https://api.example.com/v1" # Optional, for web embedding models
export EMBEDDING_MODEL_NAME="text-embedding-3-small"   # Optional, embedding model name
export LOCAL_EMBEDDING="true"                         # Optional, use local embedding model (default: true)

2. Global Config File (Recommended for Local Use)

For convenience, you can create a global configuration file. The tool will automatically look for it.

1. Create the directory: mkdir -p ~/.readmex
2. Create the config file: ~/.readmex/config.json
3. Add your credentials and any optional settings. You can also include personal information, which will be used as defaults during interactive prompts:

{
  "LLM_API_KEY": "your_llm_api_key",
  "T2I_API_KEY": "your_t2i_api_key",
  "LLM_BASE_URL": "https://api.example.com/v1",
  "T2I_BASE_URL": "https://api.example.com/v1",
  "LLM_MODEL_NAME": "gpt-4",
  "T2I_MODEL_NAME": "dall-e-3",
  "EMBEDDING_API_KEY": "your_embedding_api_key",
  "EMBEDDING_BASE_URL": "https://api.example.com/v1",
  "EMBEDDING_MODEL_NAME": "text-embedding-3-small",
  "LOCAL_EMBEDDING": "true",
  "github_username": "your_github_username",
  "twitter_handle": "your_twitter_handle",
  "linkedin_username": "your_linkedin_username",
  "email": "[e-mail]"
}

(back to top)

💻 Usage

Once installed, you can use the readmex package in the command line. To generate your README, run the following:

Method 1: Using the installed command (Recommended)

readmex

Method 2: Running as a Python module

# Run the package directly
python -m readmex

# Or run the CLI module specifically
python -m readmex.utils.cli

Method 3: Development mode (for contributors)

# From the project root directory
python src/readmex/utils/cli.py

Command Line Options

All methods support the same command line arguments:

# Interactive mode (default)
readmex

# Generate for current directory
readmex .

# Generate for specific directory
readmex /path/to/your/project

# Generate MkDocs website
readmex --website

# Generate website and serve locally
readmex --website --serve

# Deploy to GitHub Pages
readmex --deploy

# Enable debug mode (skip LLM calls for testing)
readmex --debug

# Enable silent mode (auto-generate without prompts)
readmex --silent

# Enable verbose mode (show detailed information)
readmex --verbose

This will:

1. generate a project_structure.txt file, which contains the project structure.
2. generate a script_description.json file, which contains the description of the scripts in the project.
3. generate a requirements.txt file, which contains the requirements of the project.
4. generate a logo.png file, which contains the logo of the project.
5. generate a README.md file, which contains the README of the project.

(back to top)

🗺️ Roadmap

• Prompt Engineering for Logo Generation
• Multi-language Support
• Enhanced AI Descriptions for Project Features

See the open issues for a full list of proposed features (and known issues).

(back to top)

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

🎗 License

Copyright © 2024-2025 readmex.
Released under the MIT license.

(back to top)

📧 Contact

Email: [e-mail]

Project Link: https://github.com/aibox22/readmex

QQ Group: 2161023585 (Welcome to join our QQ Group to discuss and get help!)

Scan QR code to join our QQ Group

(back to top)

⭐ Star History