Doc Generate API Mindspore

API Documentation Guide (API文档生成指南)

This skill generates Python API documentation in English docstrings (.py) and/or Chinese RST docs (.rst).

Workflow (工作流程)

Before Generation (生成前)

0. Ask generation scope: Use the question tool to ask the user (single choice, labels in Chinese):

   • 两者都生成（默认）— both English and Chinese
   • 仅英文 — English docstring only
   • 仅中文 — Chinese RST doc only

1. Collect references: PR links, test files, design docs, issue descriptions

2. Read the source code: Understand function signatures, parameter types, return values

3. Verify parameter types: Cross-reference type hints with references for untyped params

4. Run or infer examples: Get actual output values from test files or references

5. Check existing files (if scope includes Chinese RST): Search the docs directory for existing .rst files.

   • Search method: (a) by dotted path pattern — use glob with *<api_name>.rst across docs/, or (b) by content — use grep for the API name within .rst files under docs/.
   • Current API found → Use its current filename; skip Naming Convention + Path Mapping + trimming prompt.
   • Current API not found, but sibling APIs (other functions/classes in the same .py file) have RST files → Derive the naming convention from the sibling's filename (e.g., if sibling uses pkg.module.API, trim the source filename segment); skip project-wide pattern alignment; proceed to step 6 Path Mapping only.
   • No RST found for current API or any sibling → Proceed to step 6 for full Naming Convention + Path Mapping.

6. Identify naming + file paths (only when no existing file): Determine the .py source path. Determine the dotted path via Naming Convention (filename = title = directive), check the depth threshold and ask the user if trimming is needed. Then determine the output directory via Path Mapping.

Output Target (输出目标)

Naming Convention (命名规范)

RST filename = title (1st line) = .. py:: directive path. One file per API, all three always identical.

The full dotted path from the package root is the default. For deeply nested paths, the user may trim intermediate levels — all three use the shorter path together.

Rules:

• Default: full path starting from the package root (e.g., mindspore.ops.affine_grid), always includes the package name. The package root is the top-level Python package directory in the repo (typically matches the repo name or main source dir), not inferred from internal import statements.
• Trimming: when full path is overly deep, user trims middle segments. Package + API name always kept.
• Depth threshold with project pattern alignment: Determine the dotted path as follows:
  1. Start from the full dotted path at the package root.
  2. Check existing .rst files in the project's docs directory. If the prevailing pattern consistently omits the source filename (e.g., pkg.module.API rather than pkg.module.filename.API), automatically trim accordingly to match.
  3. If the resulting path exceeds 4 levels (e.g., mindspore.a.b.c.ReLU is 5 levels), must ask the user whether to trim further. Provide concrete trimming suggestions — list options that keep package + API name and remove different combinations of middle segments. 4 levels or fewer use the current path directly without asking.
• Exception: MindSpore ops func_ prefix in filename, removed in title/directive.

The dotted path determines the filename, title, and directive — all three must always be identical.

Examples:

For the exception row (3rd), the func_ prefix is present in the filename but omitted from the title and directive.