configure-docs

/configure:docs

检查并配置代码文档规范和生成器。

何时使用此技能

在以下情况下使用此技能……	在以下情况下采用其他方式……
为项目设置 TSDoc、JSDoc、pydoc 或 rustdoc 规范	编写函数或模块的实际文档内容
配置文档生成器（TypeDoc、MkDocs、Sphinx、rustdoc）	将文档部署到 GitHub Pages（请改用 /configure:github-pages）
审核文档覆盖率和 lint 合规性	检查生成的文档是否准确
在 CI/CD 中添加文档强制规则	编辑 ruff 或 biome 配置以处理非文档规则（请改用 /configure:linting）
在不同文档规范之间迁移（例如，从 numpy 风格迁移到 google 风格）	仅设置 pre-commit 钩子（请改用 /configure:pre-commit）

上下文

• 项目根目录：!pwd
• 包文件：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' \)
• Biome 配置：!find . -maxdepth 1 -name 'biome.json'
• TSDoc 配置：!find . -maxdepth 1 \( -name 'tsdoc.json' -o -name 'typedoc.json' \)
• Python 配置：!find . -maxdepth 1 \( -name 'pyproject.toml' -o -name 'ruff.toml' -o -name '.ruff.toml' \)
• Rust 配置：!find . -maxdepth 1 \( -name 'Cargo.toml' -o -name 'clippy.toml' \)
• Pre-commit：!find . -maxdepth 1 -name '.pre-commit-config.yaml'
• 文档生成器：!find . -maxdepth 1 \( -name 'mkdocs.yml' -o -name 'docusaurus.config.*' \)
• 文档目录：!find . -maxdepth 1 -type d -name 'docs'

参数

从命令参数中解析：

• --check-only：报告合规状态，不进行修改（CI/CD 模式）
• --fix：自动应用修复，不提示确认
• --level <minimal|standard|strict>：文档强制级别（默认：standard）
• --type <typescript|javascript|python|rust>：覆盖语言检测结果
• --generator <typedoc|sphinx|mkdocs|rustdoc>：覆盖文档生成器检测结果

强制级别：

• minimal：仅验证语法（文档注释有效）
• standard：要求为公共 API 编写文档（推荐）
• strict：要求为所有项目编写文档，包括私有项目

生成器自动检测：

项目类型	默认生成器
TypeScript/JavaScript	TypeDoc
Python	MkDocs（更简单）或 Sphinx
Rust	rustdoc
多语言/其他	MkDocs

执行

执行此文档规范配置检查：

第 1 步：检测项目语言

根据文件结构识别语言：

标识	语言
package.json + tsconfig.json	TypeScript
package.json（无 tsconfig）	JavaScript
pyproject.toml 或 *.py 文件	Python
Cargo.toml	Rust

对于多语言项目，为检测到的每种语言进行配置。允许使用 --type 覆盖参数来指定一种语言。

第 2 步：分析当前文档状态

针对检测到的每种语言，检查现有配置：

TypeScript/JavaScript：

• 存在 tsdoc.json（TypeScript）
• Biome 已配置为整理导入项
• 已配置 TypeDoc 或 API Extractor 以生成文档

Python：

• pyproject.toml 包含 [tool.ruff.lint.pydocstyle] 部分
• 已指定规范（google、numpy、pep257）
• ruff lint select 中已启用 D 规则

Rust：

• Cargo.toml 包含 [lints.rust] 部分
• 已配置 missing_docs lint
• 包含用于 rustdoc 专用 lint 的 [lints.rustdoc] 部分

第 3 步：生成合规报告

打印格式化的合规报告：

Documentation Standards Compliance Report
=========================================
Project: [name]
Languages: [detected languages]
Enforcement Level: [minimal|standard|strict]

Linting Standards:
  TypeScript/JavaScript:
    tsdoc.json              [PASS | MISSING | N/A]
    TypeDoc configured      [PASS | MISSING | OUTDATED]
    API docs generated      [PASS | DISABLED]

  Python:
    ruff pydocstyle        [PASS | MISSING]
    convention             [google | not set]
    D rules enabled        [PASS | DISABLED]

  Rust:
    missing_docs lint      [PASS | DISABLED]
    rustdoc lints          [PASS | PARTIAL]

Documentation Generator:
  Generator type         [typedoc|mkdocs|sphinx|rustdoc]  [DETECTED | SUGGESTED]
  Config file            [config path]                     [EXISTS | MISSING]
  Build script           [command]                         [EXISTS | MISSING]
  Output directory       [docs/|site/|target/doc/]         [EXISTS | NOT BUILT]

Overall: [X issues found]

Next Steps:
  - Run `[build command]` to generate documentation locally
  - Run `/configure:github-pages` to set up deployment

如果指定了 --check-only，则在此处停止。

第 4 步：配置文档规范（如果指定了 --fix 或用户确认）

根据检测到的语言应用配置。使用 REFERENCE.md 中的模板：

TypeScript 配置

1. 创建带有架构引用的 tsdoc.json
2. 安装 TypeDoc：npm install --save-dev typedoc
3. 创建包含入口点和输出目录的 typedoc.json

Python 配置

1. 在 pyproject.toml 中更新 [tool.ruff.lint.pydocstyle] 部分
2. 将约定设为 google（科学项目可设为 numpy）
3. 配置特定级别的规则（最低：仅 D1；标准：使用约定对应的 D 规则；严格：所有 D 规则）

Rust 配置

1. 在 Cargo.toml 中更新 [lints.rust] 部分
2. 将 missing_docs 设为 "warn"（标准）或 "deny"（严格）
3. 添加 [lints.rustdoc] 部分以检测失效链接

第 5 步：配置文档测试

创建测试以验证文档是否符合要求：

1. TypeScript/JavaScript：添加运行 typedoc --emit none 的 docs:check 脚本
2. Python：添加一个测试文件，对源代码运行 ruff check --select D
3. Rust：在 CI 中添加 cargo doc --no-deps 和 cargo clippy -- -W missing_docs

使用 REFERENCE.md 中的测试模板。

第 6 步：设置文档生成器

自动检测或配置文档站点生成器：

1. 检查是否已有生成器配置（若有则使用现有配置）
2. 如果提供了 --generator，则使用指定的生成器
3. 否则，根据检测到的项目类型进行匹配
4. 创建配置文件并添加构建脚本

使用 REFERENCE.md 中的生成器模板。

第 7 步：添加 pre-commit 集成

如果存在 .pre-commit-config.yaml，则为检测到的语言添加文档钩子。使用 REFERENCE.md 中的钩子模板。

第 8 步：更新标准跟踪

更新 .project-standards.yaml：

standards_version: "2025.1"
project_type: "[detected]"
last_configured: "[timestamp]"
components:
  docs: "2025.1"
  docs_level: "[minimal|standard|strict]"
  docs_languages: ["typescript", "python", "rust"]

详细配置模板请参阅 REFERENCE.md。

输出

提供：

1. 按语言列出的合规报告
2. 已进行的更改列表（如果使用 --fix）或拟议的更改列表（如果使用交互模式）
3. 运行文档测试的说明
4. 改进覆盖率的后续步骤

Agent 优化

场景	命令
快速合规检查	/configure:docs --check-only
自动修复所有问题	/configure:docs --fix
检查 TSDoc 有效性	`typedoc --emit none 2>&1
检查 Python 文档字符串	ruff check --select D --output-format=github
检查 Rust 文档 lint	`cargo doc --no-deps 2>&1
构建文档（MkDocs）	`mkdocs build --strict 2>&1

另请参阅

• /configure:github-pages - 设置 GitHub Pages 部署
• /configure:all - 运行所有合规检查
• /configure:status - 快速查看合规情况
• /configure:pre-commit - 配置 pre-commit 钩子
• biome-tooling 技能，适用于 TypeScript/JavaScript
• ruff-linting 技能，适用于 Python
• rust-development 技能，适用于 Rust