Skip to content

Commit 0979506

Browse files
committed
docs: improve xrobot_create_mod usage, add CI section, and expand README template.
1 parent 3864b19 commit 0979506

File tree

3 files changed

+51
-9
lines changed

3 files changed

+51
-9
lines changed

README.md

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -339,15 +339,15 @@ static void XRobotMain(HardwareContainer &hw) {
339339

340340
### `xrobot_create_mod`
341341

342-
该工具用于快速创建一个符合 XRobot 模块规范的目录结构,包含头文件、README、CMake 配置等,便于模块开发初始化。
342+
该工具用于快速创建一个符合 XRobot 模块规范的目录结构,包含头文件、README、CMake 配置等,便于模块开发初始化。
343343
This tool quickly scaffolds a new XRobot module with standard files including header, README, and CMake setup, to accelerate module development.
344344

345345
#### 🚀 使用方法 / Usage
346346

347347
```bash
348348
# 创建一个名为 MyModule 的模块
349349
# Create a module named MyModule
350-
xrobot_create_mod MyModule --desc "LED blinker" --hw led button --repo https://github.com/yourorg/MyModule
350+
xrobot_create_mod MyModule --desc "LED blinker" --hw led button
351351
```
352352

353353
#### 🎛️ 命令行参数 / Command-Line Arguments
@@ -376,27 +376,38 @@ xrobot_create_mod MyModule --desc "LED blinker" --hw led button --repo https://g
376376
依赖模块名列表。可选。
377377
List of dependent modules. Optional.
378378

379-
- `--repo`
380-
GitHub 仓库地址(可选)。
381-
GitHub repository URL (optional).
382-
383379
- `--out`
384380
输出路径,默认为 `Modules/`。
385381
Output folder. Default: `Modules/`.
386382

387383
#### 📂 生成结构 / Generated Structure
388384

389-
假设模块名为 `BlinkLED`,会生成以下文件结构:
385+
假设模块名为 `BlinkLED`,会生成以下文件结构:
390386
If the module name is `BlinkLED`, the following structure will be generated:
391387

392388
```text
393389
Modules/
394390
└── BlinkLED/
391+
├── .github/workflows/build.yml # CI 配置 / CI configuration
395392
├── BlinkLED.hpp # 带 manifest 的头文件 / Header file with manifest
396393
├── README.md # 模块文档 / Module documentation
397394
└── CMakeLists.txt # 构建配置 / Build configuration
398395
```
399396

397+
## 💡 CI 用途说明 / What is CI for?
398+
399+
生成的模块会包含一个**GitHub Actions**持续集成(CI)配置:
400+
- 自动拉取 libxr 依赖并编译模块
401+
- 支持每次 push、PR、以及每月定时自动测试
402+
- CI 失败能及时发现语法或集成问题
403+
- 保证你的模块长期可编译、易于合作开发
404+
405+
The generated module includes a GitHub Actions CI workflow that:
406+
- Pulls libxr as dependency and builds your module
407+
- Runs on every push, pull request, and a monthly schedule
408+
- Helps catch integration/compile issues automatically
409+
- Keeps your module always buildable for you and your team
410+
400411
---
401412

402413
### `xrobot_mod_parser`

pyproject.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "xrobot"
7-
version = "0.2.2"
7+
version = "0.2.3"
88
description = "A lightweight application framework for robot module management, lifecycle control, and hardware abstraction."
99
requires-python = ">=3.8"
1010
authors = [

src/xrobot/ModuleCreator.py

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,15 @@ class {class_name} : public LibXR::Application {{
4747
4848
## Required Hardware
4949
{hardware}
50+
51+
## Constructor Arguments
52+
{constructor_args}
53+
54+
## Template Arguments
55+
{template_args}
56+
57+
## Depends
58+
{depends}
5059
"""
5160

5261
GITHUB_ACTIONS_WORKFLOW = """name: XRobot Module Build Test
@@ -217,6 +226,25 @@ def parse_arg(arglist):
217226
result.append({s.strip(): ""})
218227
return result
219228

229+
def format_args(args: Optional[List[Dict[str, Any]]]) -> str:
230+
"""Format constructor or template args as markdown list"""
231+
if not args:
232+
return "None"
233+
lines = []
234+
for arg in args:
235+
key = list(arg.keys())[0]
236+
val = arg[key]
237+
if val != "":
238+
lines.append(f"- `{key}`: {val}")
239+
else:
240+
lines.append(f"- `{key}`")
241+
return "\n".join(lines)
242+
243+
def format_depends(depends: Optional[List[str]]) -> str:
244+
if not depends:
245+
return "None"
246+
return "\n".join(f"- {dep}" for dep in depends)
247+
220248
def create_module(
221249
class_name: str,
222250
description: str,
@@ -247,7 +275,10 @@ def create_module(
247275
readme_code = README_TEMPLATE.format(
248276
class_name=class_name,
249277
description=description,
250-
hardware=", ".join(required_hardware) if required_hardware else "None"
278+
hardware=", ".join(required_hardware) if required_hardware else "None",
279+
constructor_args=format_args(constructor_args),
280+
template_args=format_args(template_args),
281+
depends=format_depends(depends),
251282
)
252283

253284
(mod_dir / f"{class_name}.hpp").write_text(hpp_code, encoding="utf-8")

0 commit comments

Comments
 (0)