菜单
Write and review Python documentation using Sphinx/rST style docstrings for mkdocstrings. Use when writing docstrings, documenting classes, methods, or reviewing documentation for proper formatting.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Apply clean-code heuristics when reviewing or writing code. Use when: spotting duplicate branches, fixing API contracts that push work onto callers, simplifying conditionals, or identifying structural smells that make code hard to extend.
Design or review pybasin experiments and benchmarks where measurement structure matters. Use when creating or fixing notebooks or scripts for solver, trajectory, or feature-extraction comparisons and you need to choose `JaxSolver` save semantics (`t_span`, `t_steps`, `t_eval`), decide what should be integrated once and reused versus reintegrated per batch size, keep hot paths batched, reuse expensive benchmark artifacts across notebook cells, or report results in one decision-focused table without duplicated summaries.
Write and revise documentation (Markdown, prose sections) so that the text reads naturally and avoids patterns commonly flagged as AI-generated. Use when creating or editing .md files, case study pages, README sections, or any prose-heavy documentation.
Rework a tstorch calculator domain as one coherent migration - make every feature in that domain faster than tsfresh's CPU implementation, keep numerical output identical, confirm torch.compile(fullgraph=True)/torch.export safety, lock all of that in with regression tests and Google-style docs, and wire the domain into TorchFeatureExtractor's SUPPORTED_FEATURES in a clean way. Use when fixing a calculator file under packages/tstorch/src/tstorch/calculators/, adding a new domain, or working through batched-migration-wip.md's 'Not started' list.
| name | python-documentation-writer |
| description | Write and review Python documentation using Sphinx/rST style docstrings for mkdocstrings. Use when writing docstrings, documenting classes, methods, or reviewing documentation for proper formatting. |
Guidelines for writing Python documentation that renders correctly with mkdocstrings (Sphinx style).
uv run python .github/skills/python-documentation-writer/check_docstrings.py path/to/file.py
The linter detects: Google/NumPy style sections, missing blank lines before bullet lists, indented parameter blocks, redundant :vartype: tags.
| Element | Syntax |
|---|---|
| Parameter | :param name: Description. |
| Return | :return: Description. |
| Exception | :raises TypeError: Description. |
| Instance var | :ivar name: Description. (in class docstring) |
| Attribute type | self.name: Type = value in __init__ (required) |
Use :param:, :return:, :raises:. Do NOT use Google (Returns:) or NumPy style.
def integrate(self, ode_system: ODESystem, y0: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
"""
Integrate the ODE system from initial conditions.
:param ode_system: The ODE system to integrate.
:param y0: Initial conditions tensor of shape (batch, state_dim).
:return: Tuple of (time points, solution trajectories).
:raises ValueError: If y0 has incorrect shape.
"""
Use :ivar: in class docstring + explicit type annotations in __init__:
class Solution:
"""
Represents the result of integrating an ODE system.
:ivar initial_condition: Initial conditions used for integration.
:ivar time: Time points of the integration.
:ivar y: Solution trajectories of shape (N, B, S).
"""
def __init__(self, initial_condition: torch.Tensor, time: torch.Tensor, y: torch.Tensor):
self.initial_condition: torch.Tensor = initial_condition
self.time: torch.Tensor = time
self.y: torch.Tensor = y
Critical: Always annotate types explicitly (self.x: Type = x). Type inference does not work for docs.
Bullet lists: Always add a blank line before:
"""
The errors are based on Bernoulli statistics:
- e_abs = sqrt(S_B(A) * (1 - S_B(A)) / N)
- e_rel = 1 / sqrt(N * S_B(A))
"""
Code examples: Use fenced blocks with language specifier. Do NOT use >>> or ::.
"""
Example:
```python
estimator = BasinStabilityEstimator(ode_system, sampler)
```
"""
After the linter passes, verify: