rspress-api-docs

savvy-web 的头像作者 savvy-web

从 TypeScript 源代码为 RSPress 生成 API 文档。在记录包 API、从源代码提取类型或创建函数/类参考页面时使用。

📖 中文导读:从 TypeScript 源代码为 RSPress 生成 API 文档。在记录包 API、从源代码提取类型或创建函数/类参考页面时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: rspress-api-docs description: Generate API documentation from TypeScript source code for RSPress. Use when documenting package APIs, extracting types from source code, or creating function/class reference pages. allowed-tools: Read, Write, Edit, Glob, Grep

RSPress API Documentation

You are a specialized skill for generating API documentation from TypeScript source code in the Savvy Web Workflow documentation site.

Documentation Approaches

Manual Documentation (Recommended): Read source files, extract type signatures, and write structured markdown. This approach gives you full control over content organization and clarity.

Automated Documentation (Limited): Tools like TypeDoc can generate docs, but require integration setup and often produce verbose output that needs editing.

This skill focuses on the manual approach for better results.

API Documentation Directory

API reference documentation lives under package directories:

docs/src/en/packages/@savvy-web/{package}/api/
├── index.md              # API overview and exports list
├── functions/            # Function reference pages
│   ├── index.md
│   └── function-name.md
├── types/                # Type and interface reference
│   ├── index.md
│   └── type-name.md
└── classes/              # Class reference pages
    ├── index.md
    └── class-name.md

Manual Documentation Workflow

  1. Find the source code - Use Glob to locate package source files
  2. Identify exports - Use Grep to find exported functions, types, classes
  3. Read source files - Extract type signatures, JSDoc comments
  4. Create markdown pages - Write structured documentation for each export
  5. Link from index - Add entries to api/index.md for navigation

Function Documentation

Create function reference pages at api/functions/{function-name}.md:

# functionName

Brief description of what the function does.

## Signature

```typescript
function functionName<T>(param1: string, param2: T): Promise<Result>

Parameters

Name Type Description
param1 string Description of parameter
param2 T Generic parameter

Returns

Promise<Result> - Description of return value

Examples

const result = await functionName('value', { data: true });
console.log(result);

Throws

  • Error - When validation fails
  • TypeError - When parameters are invalid

<!-- markdownlint-disable MD024 -->

## Type/Interface Documentation

Create type reference pages at `api/types/{type-name}.md`:

```markdown
# TypeName

Brief description of what this type represents.

## Definition

```typescript
interface TypeName {
  property1: string;
  property2?: number;
  method(): void;
}

Properties

Property Type Required Description
property1 string Yes Description of property
property2 number No Optional property

Methods

method()

Description of the method.

Returns: void

Usage

const example: TypeName = {
  property1: 'value',
  method() {
    console.log('called');
  }
};

## Class Documentation

Create class reference pages at `api/classes/{class-name}.md`:

```markdown
# ClassName

Brief description of the class purpose.

## Constructor

```typescript
constructor(param1: string, options?: Options)

Parameters

Name Type Description
param1 string Required parameter
options Options Optional config

Properties

Property Type Description
name string Read-only property

Methods

methodName(param: Type): ReturnType

Description of what the method does.

Example:

const instance = new ClassName('value');
const result = instance.methodName(param);

<!-- markdownlint-enable MD024 -->

## Extracting Exports from Source

Use these patterns to find exports in TypeScript files:

**Find all exports**:

```bash
grep -r "^export " src/

Find exported functions:

grep -r "^export function " src/

Find exported types:

grep -r "^export (type|interface) " src/

Find exported classes:

grep -r "^export class " src/

API Index Page

Create an overview at api/index.md:

# API Reference

Complete API reference for @savvy-web/package-name.

## Functions

* [functionName](./functions/function-name.md) - Brief description

## Types

* [TypeName](./types/type-name.md) - Brief description

## Classes

* [ClassName](./classes/class-name.md) - Brief description

Tips

  • Extract JSDoc comments from source code for descriptions
  • Include practical examples that users can copy
  • Link related types and functions together
  • Keep parameter tables concise but complete
  • Test code examples before documenting them
  • Use proper TypeScript syntax highlighting
  • Follow existing documentation patterns in the project