mcpField
R
readme-generator

readme-generator

github.com/wedsamuel1230开发28131 次安装2 周前更新
代码仓库

关于 readme-generator

面向创客项目的 README 生成技能，帮助项目作者整理文档并面向初学者说明项目。可交互收集信息，也能扫描现有项目代码提取配置和依赖信息。

主要功能

  1. 01生成项目 README
  2. 02提供交互式信息收集
  3. 03扫描代码提取引脚与库
  4. 04包含接线图和文档模板
  5. 05覆盖安装与配置说明

适用场景

  1. 01为创客项目编写文档
  2. 02发布项目到 GitHub 或 Instructables
  3. 03从现有 Arduino 项目生成 README

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wedsamuel1230/embedded-engineering-skills --skill readme-generator

安装后在 Claude Code 中输入/readme-generator确认已加载。

附带文件scripts/generate_readme.py

详细介绍

README 生成器

为创客项目创建专业、易于初学者阅读的 README 文件。

资源

此技能包含以下打包工具：

  • scripts/generate_readme.py - 功能完整的 README 生成器，包含接线图和模板

快速开始

交互模式：

uv run --no-project scripts/generate_readme.py --interactive

快速生成：

uv run --no-project scripts/generate_readme.py --project "Weather Station" --board "ESP32" --output README.md

扫描现有项目：

uv run --no-project scripts/generate_readme.py --scan /path/to/arduino/project --output README.md

适用场景

  • “帮我为这个项目编写文档”
  • “我想在 GitHub 上分享这个项目”
  • “为我的项目编写 README”
  • 用户已有可运行的项目，需要编写文档
  • 在发布到 GitHub/Instructables 之前

信息收集

向用户询问：
1. Project name and one-line description
2. What problem does it solve / why did you build it?
3. Main features (3-5 bullet points)
4. Hardware components used
5. Software libraries required
6. Any photos/videos/GIFs available?
7. License preference (MIT recommended for open source)
8. Target audience (beginners/intermediate/advanced)
从代码中自动提取：
  • config.h 中的引脚分配
  • 库导入语句
  • WiFi/Bluetooth 功能
  • 传感器类型

README 模板

按照以下结构生成（基于 awesome-readme 的最佳实践）：

# 🎯 [Project Name]

![Project Status](https://img.shields.io/badge/status-active-brightgreen)
![Platform](https://img.shields.io/badge/platform-ESP32-blue)
![License](https://img.shields.io/badge/license-MIT-green)

> One-line description of what this project does and why it's useful.

![Project Photo/GIF](images/project-demo.gif)

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Hardware Components](#hardware-components)
- [Wiring Diagram](#wiring-diagram)
- [Software Dependencies](#software-dependencies)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## 🔍 Overview

[2-3 paragraphs explaining:]
- What the project does
- Why you built it / what problem it solves
- Who it's for (target audience)

### Demo

[Embed video or GIF showing project in action]

## ✨ Features

- ✅ Feature 1 - brief description
- ✅ Feature 2 - brief description
- ✅ Feature 3 - brief description
- 🚧 Planned: Feature 4 (coming soon)

## 🔧 Hardware Components

| Component | Quantity | Purpose | Notes |
|-----------|----------|---------|-------|
| [MCU Board] | 1 | Main controller | [version/variant] |
| [Sensor 1] | 1 | [function] | [I2C address, etc.] |
| [Display] | 1 | User interface | [resolution] |
| ... | ... | ... | ... |

**Estimated Cost:** $XX-XX

### Where to Buy

- [Component 1](link) - Amazon/AliExpress
- [Component 2](link) - Adafruit/SparkFun

## 📐 Wiring Diagram

![Wiring Diagram](images/wiring-diagram.png)

### Pin Connections

| MCU Pin | Component | Pin | Function |
|---------|-----------|-----|----------|
| GPIO21 | BME280 | SDA | I2C Data |
| GPIO22 | BME280 | SCL | I2C Clock |
| GPIO4 | LED | Anode | Status indicator |
| ... | ... | ... | ... |

## 💻 Software Dependencies

### Required Software

- [Arduino IDE](https://www.arduino.cc/en/software) (v2.0+) or [PlatformIO](https://platformio.org/)
- [Board package] - [installation link]

### Required Libraries

| Library | Version | Purpose | Install via |
|---------|---------|---------|-------------|
| [Library1] | >=1.0.0 | [function] | Library Manager |
| [Library2] | >=2.3.0 | [function] | Library Manager |
| ... | ... | ... | ... |

## 📦 Installation

### Option 1: Arduino IDE

1. **Install Arduino IDE**
   - Download from [arduino.cc](https://www.arduino.cc/en/software)
   
2. **Add Board Support** (if using ESP32/RP2040)

文件 → 首选项 → 附加开发板管理器网址： https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Then: Tools → Board → Boards Manager → Search "[board]" → Install

3. **Install Required Libraries**
- Sketch → Include Library → Manage Libraries
- Search and install each library from the table above

4. **Clone or Download This Repository**
```bash
git clone https://github.com/[username]/[repo-name].git

或下载 ZIP 并解压

  1. 打开项目
    • 在 Arduino IDE 中打开 [project-name].ino
选项 2：PlatformIO（推荐高级用户使用）

  1. 安装 VS Code 和 PlatformIO 扩展

  2. 克隆并打开：

    git clone https://github.com/[username]/[repo-name].git
cd [repo-name]
code .

  3. PlatformIO 将从 platformio.ini 自动安装依赖项

⚙️ 配置

上传前，请自定义 config.h：

// === NETWORK SETTINGS ===
#define WIFI_SSID     "your-wifi-name"
#define WIFI_PASSWORD "your-wifi-password"

// === HARDWARE PINS ===
#define LED_PIN       4
#define SENSOR_SDA    21
#define SENSOR_SCL    22

// === FEATURE FLAGS ===
#define ENABLE_OLED   true
#define ENABLE_WIFI   true
#define DEBUG_MODE    true
特定环境设置
设置开发环境生产环境
DEBUG_MODEtruefalse
SERIAL_BAUD1152009600
SLEEP_INTERVAL10s300s

🚀 使用方法

基本操作
  1. 开机 - 连接 USB 或电池
  2. 等待启动 - 初始化期间状态 LED 会闪烁
  3. [正常运行] - 描述运行时的情况
LED 状态指示
LED 状态含义
常亮绿灯正常运行
闪烁蓝灯正在连接 WiFi
红灯闪烁错误（检查串口）
串口监视器

以 115200 波特率打开串口监视器，查看：

[BOOT] Project Name v1.0.0
[INFO] Initializing sensors...
[OK] BME280 found at 0x76
[INFO] Connecting to WiFi...
[OK] Connected: 192.168.1.100
[DATA] Temp: 23.5°C, Humidity: 45%
Web 界面（如适用）

访问 http://[device-ip]，即可使用：

  • 实时传感器读数
  • 配置面板
  • 数据导出

❓ 故障排除

常见问题
上传失败：“Failed to connect”

ESP32： 点击“上传”时按住 BOOT 按钮，出现“Connecting...”后松开。

Arduino： 在“工具”→“端口”中检查是否选择了正确的 COM 端口。

未检测到传感器
  1. 检查接线（SDA/SCL 是否接反？）
  2. 运行 I2C 扫描器草图以确认地址
  3. 如果模块上没有上拉电阻，请添加 4.7kΩ 上拉电阻
  4. 检查电压是否兼容（3.3V 还是 5V）
WiFi 无法连接
  1. 检查 config.h 中的 SSID/密码（区分大小写！）
  2. 仅支持 2.4GHz（ESP32 不支持 5GHz）
  3. 检查路由器是否阻止了新设备
  4. 尝试移近路由器
随机重启
  1. 电源过弱——请使用 500mA 以上的电源
  2. 在 MCU 附近添加一个 100µF 电容
  3. 检查是否存在短路
  4. 禁用欠压检测器（ESP32）
仍然无法解决？
  1. 在 Issues 中查找类似问题
  2. 提交新问题，并附上：
    • 硬件配置（开发板、传感器）
    • 错误消息（完整串口输出）
    • 复现步骤

🤝 参与贡献

欢迎贡献！参与方式如下：

报告错误
  1. 先检查现有问题
  2. 使用错误报告模板
  3. 附上串口输出和硬件详情
提出功能建议
  1. 创建问题，并在标题前加上 [Feature Request]
  2. 描述使用场景和预期行为
拉取请求
  1. Fork 此仓库
  2. 创建功能分支：git checkout -b feature/amazing-feature
  3. 进行更改
  4. 充分测试
  5. 提交：git commit -m 'Add amazing feature'
  6. 推送：git push origin feature/amazing-feature
  7. 发起拉取请求
代码风格
  • 使用有意义的变量名
  • 为复杂逻辑添加注释
  • 遵循现有格式
  • 在提交 PR 前使用实际硬件测试

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

MIT License

Copyright (c) [year] [author]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🙏 致谢

  • [Library/Project] - 感谢其提供的 [what it provides]
  • [Person/Tutorial] - 提供灵感/指导
  • [Community] - 参与测试并提供反馈

📬 联系方式

[Your Name] - @twitter_handle - [email protected]

项目链接：https://github.com/[username]/[repo-name]

⭐ 如果此项目对你有帮助，请为它点个星！


---

## Section Guidelines

### Good vs Bad Examples

**Project Description:**

❌ 不佳：“一个带传感器的 Arduino 项目” ✅ 良好：“电池供电的环境监测器，可追踪温度、湿度和空气质量，并在超过阈值时发送警报”


**Features:**

❌ 不佳：“支持 WiFi” ✅ 良好：“📶 支持 WiFi 连接，可自动重新连接并进行 OTA 更新”


**Installation Steps:**

❌ 不佳：“安装库并上传” ✅ 良好：提供包含截图、版本号和准确菜单路径的分步说明


### Visual Assets

**Recommended:**
- Project photo (hero image)
- Wiring diagram (Fritzing or hand-drawn)
- Demo GIF (< 5MB, 10-15 seconds)
- Schematic (KiCad export)

**Creating GIFs:**
- Use ScreenToGif (Windows) or Peek (Linux)
- Optimize with ezgif.com
- Keep under 5MB for GitHub

### Badges

```markdown

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![Version](https://img.shields.io/badge/version-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)


![Arduino](https://img.shields.io/badge/platform-Arduino-00979D?logo=arduino)
![ESP32](https://img.shields.io/badge/platform-ESP32-blue)
![Raspberry Pi](https://img.shields.io/badge/platform-RPi_Pico-C51A4A)


![GitHub stars](https://img.shields.io/github/stars/user/repo)
![GitHub forks](https://img.shields.io/github/forks/user/repo)

文件结构建议

project-name/
├── README.md              # Main documentation
├── LICENSE                # MIT license file
├── .gitignore            # Ignore build files
├── src/
│   ├── main.ino          # Main sketch
│   └── config.h          # User configuration
├── lib/                  # Local libraries (optional)
├── docs/
│   ├── WIRING.md         # Detailed wiring guide
│   ├── API.md            # API documentation (if applicable)
│   └── CHANGELOG.md      # Version history
├── images/
│   ├── project-photo.jpg
│   ├── wiring-diagram.png
│   └── demo.gif
├── hardware/             # PCB/enclosure files (optional)
│   ├── schematic.pdf
│   └── enclosure.stl
└── examples/             # Additional example sketches
    └── basic/

README 快速检查清单

发布前，请确认：

□ Project name is clear and memorable
□ One-line description explains the "what" and "why"
□ Hero image/GIF shows project in action
□ All hardware components listed with links
□ Wiring diagram included
□ All libraries listed with versions
□ Step-by-step installation instructions
□ Configuration section explains all settings
□ Usage section shows expected output
□ Troubleshooting covers common issues
□ License file present
□ Contact information included
□ No broken links
□ Spelling/grammar checked

共享输出约定

使用共享的 Arduino 技能约定： 说明假设、所需工具及版本、实施步骤、各证明阶段的测试/证据、已知限制，以及恢复/安全说明。

评论

支持 Markdown