{"id":50745591,"url":"https://github.com/roshhellwett/projectreadmegen","last_synced_at":"2026-06-10T20:30:46.645Z","repository":{"id":348354535,"uuid":"1197657918","full_name":"roshhellwett/projectreadmegen","owner":"roshhellwett","description":"ᴀᴜᴛᴏ-ɢᴇɴᴇʀᴀᴛᴇ ʀᴇᴀᴅᴍᴇ ꜰɪʟᴇꜱ","archived":false,"fork":false,"pushed_at":"2026-05-31T07:16:16.000Z","size":449,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T09:11:21.800Z","etag":null,"topics":["projectreadmegen","zenithopensourceprojects"],"latest_commit_sha":null,"homepage":"https://zenithopensourceprojects.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roshhellwett.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T19:09:27.000Z","updated_at":"2026-05-31T07:16:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/roshhellwett/projectreadmegen","commit_stats":null,"previous_names":["roshhellwett/projectreadmegen"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/roshhellwett/projectreadmegen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roshhellwett%2Fprojectreadmegen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roshhellwett%2Fprojectreadmegen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roshhellwett%2Fprojectreadmegen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roshhellwett%2Fprojectreadmegen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roshhellwett","download_url":"https://codeload.github.com/roshhellwett/projectreadmegen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roshhellwett%2Fprojectreadmegen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34170162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["projectreadmegen","zenithopensourceprojects"],"created_at":"2026-06-10T20:30:46.007Z","updated_at":"2026-06-10T20:30:46.632Z","avatar_url":"https://github.com/roshhellwett.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Repo Size](https://img.shields.io/github/repo-size/roshhellwett/projectreadmegen?style=for-the-badge)\n![Stars](https://img.shields.io/github/stars/roshhellwett/projectreadmegen?style=for-the-badge)\n![Forks](https://img.shields.io/github/forks/roshhellwett/projectreadmegen?style=for-the-badge)\n![Issues](https://img.shields.io/github/issues/roshhellwett/projectreadmegen?style=for-the-badge)\n![Markdown](https://img.shields.io/badge/Markdown-000000?style=for-the-badge\u0026logo=markdown\u0026logoColor=white)\n\n# PROJECT README GEN\n\nAuto-generate README files from folder structure with optional AI enhancement using Groq API.\n\n![SAMPLE](https://github.com/roshhellwett/projectreadmegen/blob/6ea4f99fbcdba0531e59835f7f492329fbefaab0/Sample/sample.png)\n\n---\n\n## Overview\n\nPoint it at any project folder. It scans your directory structure, detects the tech stack, and generates a polished `README.md` — in seconds.\n\n**Two modes:**\n- **Template-based** — 4 ready-made templates (minimal, standard, full, academic)\n- **AI-powered** — connects to Groq API for intelligent, project-aware READMEs\n\n---\n\n## Features\n\n- **Auto-detection** — identifies language, framework, license, project type, install/run commands\n- **4 templates** — minimal, standard, full, academic — each with varying detail levels\n- **AI generation** — uses Groq's LLM (llama-3.3-70b) for smart, contextual READMEs\n- **Interactive mode** — answers questions to customize output\n- **GitHub Profile README** — generates profile READMEs with stats cards, language graphs, and style presets\n- **Badge support** — automatic language + license badges via shields.io\n- **Folder tree** — includes an ASCII directory tree in your README\n- **Safe writes** — atomic file writes via temp file + move, disk space checks, permission validation\n- **Smart caching** — reuses previous scan results when project hasn't changed\n\n---\n\n## Installation\n\n```bash\npip install projectreadmegen\n```\n\nVerify it installed correctly:\n\n```bash\nprojectreadmegen --version\n```\n\nOr run via Python module:\n\n```bash\npython -m projectreadmegen --version\n```\n\n---\n\n## Quick Start\n\n### Generate a README for any project\n\n```bash\n# Navigate to your project\ncd my-project\n\n# Generate a README using the standard template\nprojectreadmegen generate .\n\n# Generate with AI (requires API key — see setup below)\nprojectreadmegen generate . --ai\n```\n\nThat's it. Your `README.md` is created in the current directory.\n\n---\n\n## Commands\n\nAll commands support `--help` for inline documentation.\n\n### `generate` — Generate a README\n\nThe primary command. Scans a project directory and writes `README.md`.\n\n```bash\nprojectreadmegen generate [PATH] [OPTIONS]\n```\n\n**Arguments:**\n\n| Argument | Description | Default |\n|---|---|---|\n| `PATH` | Path to your project directory | `.` (current dir) |\n\n**Options:**\n\n| Flag | Description |\n|---|---|\n| `--template, -t` | Template: `minimal`, `standard`, `full`, `academic` |\n| `--ai, -a, --grok` | Use Groq AI to generate the README |\n| `--auto-ai` | Auto-use AI when API key is available |\n| `--output, -o` | Output filename (default: `README.md`) |\n| `--depth, -d` | Max folder tree depth (1–10, default: 3) |\n| `--no-badges` | Disable shields.io badge generation |\n| `--force, -f` | Overwrite existing README without confirmation |\n| `--dry-run` | Print README to terminal, don't save to file |\n\n**Examples:**\n\n```bash\n# Basic — standard template\nprojectreadmegen generate .\n\n# Choose a template\nprojectreadmegen generate . --template full\nprojectreadmegen generate . -t minimal\n\n# AI-powered README\nprojectreadmegen generate . --ai\n\n# Include folder tree up to 5 levels deep\nprojectreadmegen generate . --depth 5\n\n# Preview without saving\nprojectreadmegen generate . --dry-run --template full\n\n# Custom output file\nprojectreadmegen generate . --output PROFILE.md\n\n# Disable badges\nprojectreadmegen generate . --no-badges\n\n# Overwrite existing README silently\nprojectreadmegen generate . --force\n\n# All flags together\nprojectreadmegen generate ./my-project -t full --ai --depth 4 --no-badges --output README.md\n```\n\n### `interactive` — Interactive customization\n\nWalks you through questions to customize the generated README.\n\n```bash\nprojectreadmegen interactive [PATH] [OPTIONS]\n```\n\n**Options:**\n\n| Flag | Description |\n|---|---|\n| `--ai, -a, --grok` | Use AI generation during interactive session |\n\n**Example workflow:**\n\n```bash\n# Template-based interactive\nprojectreadmegen interactive .\n# Asks for: your name, GitHub username, template choice, include tree?\n\n# AI-powered interactive\nprojectreadmegen interactive . --ai\n# Uses AI to generate, falls back to template if API key is missing\n```\n\n### `start` — Launch the interactive menu\n\nOpens the full-featured menu system shown below in the [Interactive Menu](#interactive-menu) section.\n\n```bash\nprojectreadmegen start\n```\n\n### `version` — Show version\n\n```bash\nprojectreadmegen version\nprojectreadmegen --version\nprojectreadmegen -V\n```\n\n### `update` — Check and apply updates\n\n```bash\nprojectreadmegen update\n```\n\nChecks PyPI for a newer version and upgrades automatically if one exists.\n\n---\n\n## Interactive Menu\n\nRun `projectreadmegen start` to open the menu:\n\n```\n┌──────────────────────────────────────────────┐\n│         Welcome to projectreadmegen           │\n│   Auto-generate README files with AI power    │\n│                                              │\n│  Select an option:                           │\n│                                              │\n│  1  Create README with AI                     │\n│  2  Create Normal README (template-based)     │\n│  3  Manage API Key                           │\n│  4  View Credits Status                      │\n│  5  Update projectreadmegen                   │\n│  6  Help \u0026 Commands                          │\n│  7  Create GitHub Profile README  [NEW]       │\n│  8  Exit                                     │\n└──────────────────────────────────────────────┘\n```\n\n### Option 1 — Create README with AI\n1. Choose mode: `1` (quick generate) or `2` (interactive)\n2. Enter project path (or press Enter for current dir)\n3. If no API key is detected, you'll be prompted to add one\n4. README is generated via Groq AI and saved\n\n### Option 2 — Create Normal README\n1. Choose mode: `1` (quick generate) or `2` (interactive)\n2. In interactive mode you can customize: author name, GitHub username, template, and whether to include the folder tree\n3. README is generated from templates and saved\n\n### Option 3 — Manage API Key\n- **If no key configured:** Add your own Groq API key or manage a GitHub token\n- **If key configured:** Update, remove, or manage GitHub token\n- API keys must start with `gsk_` and are stored locally in `%APPDATA%\\projectreadmegen\\` (Windows) or `~/.projectreadmegen/`\n\n### Option 4 — View Credits Status\nShows whether your Groq API key and GitHub token are configured.\n\n### Option 5 — Update\nSame as the `update` command — checks PyPI for the latest version.\n\n### Option 6 — Help \u0026 Commands\nQuick reference of all CLI commands and flags.\n\n### Option 7 — Create GitHub Profile README\nSee dedicated section below.\n\n### Option 8 — Exit\nExits the menu.\n\n---\n\n## GitHub Profile README\n\nGenerates a README for your `github.com/\u003cusername\u003e` profile repository.\n\n**Access via:** Menu option `7` or programmatically through the `github_profile` module.\n\n### What it does:\n1. Asks for your GitHub username and profile URL\n2. Fetches your profile data, repositories, and language stats via the GitHub API\n3. Lets you choose a style\n4. Generates an AI-powered profile README using Groq\n\n### Styles:\n\n| # | Style | Description |\n|---|---|---|\n| 1 | **Basic** | Clean, minimal, professional |\n| 2 | **Professional** | Career-focused with detailed sections |\n| 3 | **Stylish** | Stats cards, typing effects, badges |\n| 4 | **Unique** | Most detailed, creative, and eye-catching |\n\n### Example flow:\n\n```bash\n# Via menu\nprojectreadmegen start\n# Select option 7, enter username, choose style\n\n# The tool:\n# 1. Validates the GitHub username\n# 2. Fetches profile data from api.github.com\n# 3. Generates README with shields.io badges and stats cards\n# 4. Saves to ./\u003cusername\u003e/README.md\n```\n\n\u003e **Note:** Requires a Groq API key. A GitHub token is optional but enables richer data (all repos, accurate stats).\n\n---\n\n## API Key Setup\n\nAI features require a free Groq API key.\n\n### Get your key:\n1. Visit [console.groq.com/keys](https://console.groq.com/keys)\n2. Click **Create Key**\n3. Copy the key (starts with `gsk_`)\n\n### Set it:\n\n**Via the menu:**\n```bash\nprojectreadmegen start\n# Select option 3 → Add Your Own API Key\n```\n\n**Via environment variable (recommended for scripts):**\n```bash\n# PowerShell\n$env:GROQ_API_KEY = \"gsk_your_key_here\"\n\n# CMD\nset GROQ_API_KEY=gsk_your_key_here\n```\n\nThe key is stored locally and used for all AI features (README generation, GitHub Profile README).\n\n---\n\n## Templates\n\n| Template | Best For | Sections |\n|---|---|---|\n| **minimal** | Small utilities, scripts | Title, description, install, usage, license |\n| **standard** | Most projects | Overview, prerequisites, install, usage, structure, tests, contributing, license |\n| **full** | Major applications | Table of contents, features grid, tech stack table, install/usage with copy-ready commands, structure, tests with coverage, contributing, license, footer |\n| **academic** | Coursework, research | About, objectives checklist, install, run, file structure, concepts, author |\n\n```bash\n# Specify a template\nprojectreadmegen generate . --template academic\nprojectreadmegen generate . -t full\n```\n\nThe last-used template per project is remembered (stored in the local cache).\n\n---\n\n## Configuration\n\nCreate a `readmegen.config.json` in your project root to set persistent defaults:\n\n```json\n{\n  \"template\": \"standard\",\n  \"output_file\": \"README.md\",\n  \"include_tree\": true,\n  \"max_tree_depth\": 3,\n  \"include_badges\": true,\n  \"author\": \"\",\n  \"github_username\": \"your-username\"\n}\n```\n\n**Available keys:**\n\n| Key | Type | Default | Description |\n|---|---|---|---|\n| `template` | string | `\"standard\"` | Default template name |\n| `output_file` | string | `\"README.md\"` | Output filename |\n| `include_tree` | bool | `true` | Include folder tree in README |\n| `max_tree_depth` | int | `3` | Maximum tree depth (1–10) |\n| `include_badges` | bool | `true` | Show shields.io badges |\n| `ai_enabled` | bool | `false` | Always use AI generation |\n| `author` | string | `\"\"` | Author name for generated README |\n| `github_username` | string | `\"\"` | GitHub username for repo links |\n\n---\n\n## Error Handling\n\nprojectreadmegen handles common errors gracefully:\n\n| Scenario | Behavior |\n|---|---|\n| Path does not exist | Clear error message, exit code 1 |\n| Path is a file, not a directory | Clear error message, exit code 1 |\n| No read permission | Permission error with actionable guidance |\n| API key missing | Prompts to add one, falls back to template generation |\n| AI generation fails | Automatically falls back to template-based generation |\n| API rate limited | Exponential backoff with retries (up to 3), then clear error |\n| Disk space low | Writes prevented with space requirement info |\n| Invalid config JSON | Error message with JSON syntax details |\n\n---\n\n## Examples\n\n### Generate README for a Python project\n\n```bash\ncd my-python-project\nprojectreadmegen generate . --template full\n# Output: ./README.md with title, description, install/run commands, folder tree\n```\n\n### Generate README for a web app\n\n```bash\nprojectreadmegen generate ./react-app --template full --depth 5\n# Detects: React, TypeScript, npm\n# Includes: tech stack table, full feature list, folder tree\n```\n\n### Preview before saving\n\n```bash\nprojectreadmegen generate . --dry-run --template standard\n# Prints the generated README to the terminal\n```\n\n### AI-powered (with API key)\n\n```bash\nprojectreadmegen generate . --ai\n# Sends project context to Groq API, receives a customized README\n```\n\n---\n\n## Project Structure\n\n```\nprojectreadmegen/\n├── src/\n│   └── projectreadmegen/\n│       ├── __init__.py          # Version info\n│       ├── __main__.py          # Entry: python -m projectreadmegen\n│       ├── cli.py               # CLI commands, menu system\n│       ├── badges.py            # shields.io badge generation\n│       ├── config.py            # Language patterns, skip lists, defaults\n│       ├── detector.py          # Language, license, project type detection\n│       ├── exceptions.py        # Custom exception hierarchy\n│       ├── generator.py         # Template rendering + file writing\n│       ├── github_profile.py    # GitHub profile README generation\n│       ├── grok.py              # Groq AI client with retry logic\n│       ├── scanner.py           # Directory traversal + caching\n│       ├── usagetracker.py      # API key storage, usage tracking\n│       ├── utils.py             # Path validation, symlink checks, disk space\n│       └── templates/\n│           ├── minimal.md.j2\n│           ├── standard.md.j2\n│           ├── full.md.j2\n│           └── academic.md.j2\n├── tests/\n│   ├── test_detector.py\n│   ├── test_generator.py\n│   ├── test_github_profile.py\n│   ├── test_scanner.py\n│   └── test_usagetracker.py\n├── examples/                   # Sample projects for testing detection\n├── pyproject.toml\n├── readmegen.config.json\n└── readme.md\n```\n\n---\n© 2026 [Zenith Open Source Projects](https://zenithopensourceprojects.vercel.app/). All Rights Reserved. Zenith is a Open Source Project Idea's by [@roshhellwett](https://github.com/roshhellwett)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froshhellwett%2Fprojectreadmegen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froshhellwett%2Fprojectreadmegen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froshhellwett%2Fprojectreadmegen/lists"}