restructured-text
具有回归测试和 PR 创建的系统性错误修复工作流程。当用户要求"修复错误"、"调试问题"、"解决问题",或提供错误消息/失败测试来修复时使用。处理复现、根本原因分析、测试创建、修复实现和 PR 提交。
📖 中文导读:具有回归测试和 PR 创建的系统性错误修复工作流程。当用户要求"修复错误"、"调试问题"、"解决问题",或提供错误消息/失败测试来修复时使用。处理复现、根本原因分析、测试创建、修复实现和 PR 提交。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: restructured-text version: 1 description: "Guidelines for writing valid reStructuredText (.rst) in this repo (Sphinx)." scope: "doc/**/*.rst"
reStructuredText (Sphinx) guidelines
Core rules
- Treat
.rstas reStructuredText (not Markdown). Indentation and blank lines are semantic. - Prefer Sphinx structure over
.. include::for navigation: use.. toctree::so each page is a real document. - Avoid tabs; use spaces.
Headings
- Underlines must be at least as long as the title text.
- Keep heading levels consistent within a file.
Example::
Title
=====
Section
-------
Lists
- For enumerated/bulleted lists, indent continuation paragraphs under the list item and add a blank line between items when they contain multiple paragraphs.
Example::
1. Item title
Continuation paragraph (indented).
2. Next item
Inline markup
Escape characters that trigger markup when they are literal.
Prefer Sphinx roles for semantic markup:
- Filenames:
:file:(e.g. ``:file:`*.inp```). - Commands:
:command:. - Environment variables:
:envvar:(define them via.. envvar::somewhere in the docs).
- Filenames:
Common pitfall::
This breaks: CLEED *.res results file
Better::
Use :file:`*.res` results files
Links and references
Labels must use the underscore form:
.. _label_name:.Use ``:ref:`label_name``` for internal links.
Use explicit links for emails/URLs:
mailto:for email links.- Full URLs for external links.
Example::
See :ref:`file_formats` or email `support <mailto:someone@example.com>`_.